knife-cookbook-doc 0.9.0 → 0.10.0

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+v0.10.0 (Mar 3 2014)
+--------------------
+
+* Add support for generating documentation for definitions. Submitted by zhelyan.
+* Remove end of line whitespace in generated README
+
 v0.9.0 (Feb 24 2014)
 --------------------
 

data/README.md

@@ -80,6 +80,28 @@ to the end of the LWRP documentation.
 
 #### Step 4
 
+In each definition add documentation like:
+
+      =begin
+        #<
+        This definition does something useful.
+
+        @param user User to run as.
+        @param group User group to run as.
+
+        @section Examples
+
+            # An example of my awesome service
+            mycookbook_awesome_definition "app resources" do
+              user 'appuser'
+              group 'appgroup'
+            end
+        #>
+      =end
+
+
+#### Step 5
+
 Finally the user should add some documentation fragments into the `doc/` dir.
 Most importantly you should add `doc/overview.md` which will replace the first
 `Description` section of the readme. You should also add a `doc/credit.md` which

data/lib/chef/knife/README.md.erb

@@ -73,6 +73,35 @@
 <% else -%>
 *No recipes defined*
 
+<% end -%>
+<% unless definitions.empty? -%>
+# Definitions
+
+<% definitions.each do |definition| -%>
+* [<%= definition.name %>](#<%= definition.name %>)<% if definition.short_description %> - <%= definition.short_description %><% end %>
+<% end -%>
+
+<% definitions.each do |definition| -%>
+## <%= definition.name %>
+
+<% if definition.top_level_description('main') != '' -%>
+<%= definition.top_level_description('main') -%>
+<% end -%>
+
+<% unless definition.params.empty? -%>
+### Parameters
+
+<% definition.params.each do |param, data| -%>
+- <%= param %>: <%= data['descr'] %>.<% if data['default']%> Defaults to: <%=data['default']%><%end%>
+<% end -%>
+<% end -%>
+<% definition.top_level_descriptions.keys.select{|k| k != 'main'}.each do |key| -%>
+
+### <%= key -%>
+
+<%= definition.top_level_description(key) -%>
+<% end -%>
+<% end -%>
 <% end -%>
 <% unless resources.empty? -%>
 # Resources

data/lib/chef/knife/cookbook_doc.rb

@@ -6,6 +6,9 @@ module KnifeCookbookDoc
     deps do
       require 'chef/cookbook/metadata'
       require 'erubis'
+      require 'knife_cookbook_doc/base_model'
+      require 'knife_cookbook_doc/documenting_lwrp_base'
+      require 'knife_cookbook_doc/definitions_model'
       require 'knife_cookbook_doc/readme_model'
       require 'knife_cookbook_doc/recipe_model'
       require 'knife_cookbook_doc/resource_model'
@@ -15,22 +18,22 @@ module KnifeCookbookDoc
     banner 'knife cookbook doc DIR (options)'
 
     option :constraints,
-           :short       => '-c',
-           :long        => '--constraints',
-           :boolean     => true,
-           :default     => true,
+           :short => '-c',
+           :long => '--constraints',
+           :boolean => true,
+           :default => true,
            :description => 'Include version constraints for platforms and dependencies'
 
     option :output_file,
-           :short       => '-o',
-           :long        => '--output-file FILE',
-           :default     => 'README.md',
+           :short => '-o',
+           :long => '--output-file FILE',
+           :default => 'README.md',
            :description => 'Set the output file to render to relative to cookbook dir. Defaults to README.md'
 
     option :template_file,
-           :short       => '-t',
-           :long        => '--template FILE',
-           :default     => Pathname.new("#{File.dirname(__FILE__)}/README.md.erb").realpath,
+           :short => '-t',
+           :long => '--template FILE',
+           :default => Pathname.new("#{File.dirname(__FILE__)}/README.md.erb").realpath,
            :description => 'Set template file used to render README.md'
 
     def run
@@ -47,8 +50,11 @@ module KnifeCookbookDoc
       eruby = Erubis::Eruby.new(template)
       result = eruby.result(model.get_binding)
 
-      File.open("#{cookbook_dir}/#{config[:output_file]}",'wb') do |f|
-        f.write result
+      File.open("#{cookbook_dir}/#{config[:output_file]}", 'wb') do |f|
+        result.each_line do |line|
+          f.write line.gsub(/[ \t\r\n]*$/,'')
+          f.write "\n"
+        end
       end
     end
   end

data/lib/knife_cookbook_doc/base_model.rb

@@ -0,0 +1,44 @@
+module KnifeCookbookDoc
+  module BaseModel
+
+    def top_level_description(section)
+      (top_level_descriptions[section.to_s] || []).join("\n").gsub(/\n+$/m,"\n")
+    end
+
+    def top_level_descriptions
+      @top_level_descriptions ||= {}
+    end
+
+    def short_description
+      unless @short_description
+        @short_description = first_sentence(top_level_description('main'))
+      end
+      @short_description
+    end
+
+    private
+
+    def first_sentence(string)
+      string.gsub(/^(.*?\.(\z|\s))/m) do |match|
+        return $1.gsub("\n",' ').strip
+      end
+      return nil
+    end
+
+    def extract_description
+      description = []
+      IO.read(@filename).gsub(/^=begin *\n *\#\<\n(.*?)^ *\#\>\n=end *\n/m) do
+        description << $1
+        ""
+      end.gsub(/^ *\#\<\n(.*?)^ *\#\>\n/m) do
+        description << $1.gsub(/^ *\# ?/, '')
+        ""
+      end.gsub(/^ *\#\<\> (.*?)$/) do
+        description << $1
+        ""
+      end
+      description.join("\n")
+    end
+
+  end
+end

data/lib/knife_cookbook_doc/definitions_model.rb

@@ -0,0 +1,51 @@
+module KnifeCookbookDoc
+  class DefinitionsModel
+    include KnifeCookbookDoc::BaseModel
+    attr_reader :name
+
+    def initialize(name, filename)
+      @name = name
+      @filename = filename
+      load_descriptions
+    end
+
+    def params
+      @params ||= {}
+    end
+
+    private
+
+    def load_descriptions
+      description = extract_description
+      current_section = 'main'
+      description.each_line do |line|
+        if /^ *\@param *([^ ]*) (.*)$/ =~ line
+          params[$1] = {}
+          params[$1]['descr'] = $2.strip
+        elsif /^ *\@section (.*)$/ =~ line
+          current_section = $1.strip
+        else
+          lines = (top_level_descriptions[current_section] || [])
+          lines << line.gsub("\n", '')
+          top_level_descriptions[current_section] = lines
+        end
+      end
+      load_properties
+    end
+
+    def load_properties
+      code = IO.read(@filename)
+      code.gsub(/^ *define (.*?) (?=do)/m) do
+        all = $1.split(' ', 2)
+        @name = all.shift.gsub(/:/, '')
+        next if all.empty?
+        all = eval("{#{all.last}}") rescue {}
+        all.each do |k, v|
+          p_name = k.to_s
+          params[p_name] ||= {}
+          params[p_name]['default'] = v ? v : 'nil'
+        end
+      end
+    end
+  end
+end

data/lib/knife_cookbook_doc/readme_model.rb

@@ -27,6 +27,11 @@ module KnifeCookbookDoc
         @resources << ResourceModel.new(@metadata.name, resource_filename)
       end
 
+      @definitions = []
+      Dir["#{cookbook_dir}/definitions/*.rb"].sort.each do |def_filename|
+        @definitions << DefinitionsModel.new(File.basename(def_filename, '.*'), def_filename)
+      end
+
       @fragments = {}
       Dir["#{cookbook_dir}/doc/*.md"].sort.each do |resource_filename|
         @fragments[::File.basename(resource_filename,'.md')] = IO.read(resource_filename)
@@ -57,6 +62,10 @@ module KnifeCookbookDoc
       @resources
     end
 
+    def definitions
+      @definitions
+    end
+
     def description
       @metadata.description
     end

data/lib/knife_cookbook_doc/recipe_model.rb

@@ -1,5 +1,6 @@
 module KnifeCookbookDoc
   class RecipeModel
+    include KnifeCookbookDoc::BaseModel
 
     attr_reader :name
     attr_reader :short_description
@@ -11,14 +12,6 @@ module KnifeCookbookDoc
       load_descriptions
     end
 
-    def top_level_description(section)
-      (top_level_descriptions[section.to_s] || []).join("\n").gsub(/\n+$/m,"\n")
-    end
-
-    def top_level_descriptions
-      @top_level_descriptions ||= {}
-    end
-
     private
 
     def load_descriptions
@@ -39,27 +32,5 @@ module KnifeCookbookDoc
     end
 
     include ::Chef::Mixin::ConvertToClassName
-
-    def extract_description
-      description = []
-      IO.read(@filename).gsub(/^=begin *\n *\#\<\n(.*?)^ *\#\>\n=end *\n/m) do
-        description << $1
-        ""
-      end.gsub(/^ *\#\<\n(.*?)^ *\#\>\n/m) do
-        description << $1.gsub(/^ *\# ?/, '')
-        ""
-      end.gsub(/^ *\#\<\> (.*?)$/) do
-        description << $1
-        ""
-      end
-      description.join("\n")
-    end
-
-    def first_sentence(string)
-      string.gsub(/^(.*?\.(\z|\s))/m) do |match|
-        return $1.gsub("\n",' ').strip
-      end
-      return nil
-    end
   end
 end

data/lib/knife_cookbook_doc/resource_model.rb

@@ -1,7 +1,6 @@
-require 'knife_cookbook_doc/documenting_lwrp_base'
-
 module KnifeCookbookDoc
   class ResourceModel
+    include KnifeCookbookDoc::BaseModel
 
     attr_reader :native_resource
 
@@ -59,28 +58,6 @@ module KnifeCookbookDoc
       @attribute_descriptions ||= {}
     end
 
-    def short_description
-      unless @short_description
-        @short_description = first_sentence(top_level_description('main'))
-      end
-      @short_description
-    end
-
-    def first_sentence(string)
-      string.gsub(/^(.*?\.(\z|\s))/m) do |match|
-        return $1.gsub("\n",' ').strip
-      end
-      return nil
-    end
-
-    def top_level_description(section)
-      (top_level_descriptions[section.to_s] || []).join("\n").gsub(/\n+$/m,"\n")
-    end
-
-    def top_level_descriptions
-      @top_level_descriptions ||= {}
-    end
-
     private
 
     def load_descriptions

data/lib/knife_cookbook_doc/version.rb

@@ -1,3 +1,3 @@
 module KnifeCookbookDoc
-  VERSION = '0.9.0'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,7 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: knife-cookbook-doc
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
+  prerelease: 
 platform: ruby
 authors:
 - Mathias Lafeldt
@@ -9,11 +10,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-24 00:00:00.000000000 Z
+date: 2014-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -21,6 +23,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -28,6 +31,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: erubis
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -35,6 +39,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -42,6 +47,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -49,6 +55,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -72,6 +79,8 @@ files:
 - lib/chef/knife/README.md.erb
 - lib/chef/knife/cookbook_doc.rb
 - lib/knife_cookbook_doc/attributes_model.rb
+- lib/knife_cookbook_doc/base_model.rb
+- lib/knife_cookbook_doc/definitions_model.rb
 - lib/knife_cookbook_doc/documenting_lwrp_base.rb
 - lib/knife_cookbook_doc/readme_model.rb
 - lib/knife_cookbook_doc/recipe_model.rb
@@ -80,26 +89,26 @@ files:
 homepage: http://realityforge.github.com/knife-cookbook-doc
 licenses:
 - Apache 2.0
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Knife plugin to generate README.md for a cookbook
 test_files: []
-has_rdoc: 

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ODE3YjMyNTVmN2UzYWY3ZDVkMjE4Y2U3ZTk2MjZiZjM1MjlmZmRmMg==
-  data.tar.gz: !binary |-
-    N2NjZDhlZmVhM2M0M2Q2MzNlNDExNThjYTY0ZGQ5Nzk3M2E2OTI0Yw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    ODQwNWE3OTY5YmFmY2YyOWJhYzgyNjQ3ZmViMGZkZjAxN2E2ZDllMDEyMGQy
-    MmYzZDZkNmIzMzQ0Y2NmNGNhMTkyNzNiNWY4OGFlNGQ4ZTlhNmJjZGFiMmU2
-    NWIwN2VmZTRjZDkyNGVlZTNhNDhhMjJiMTdmNjUxMzFjMmZkZTE=
-  data.tar.gz: !binary |-
-    MTc3MWFhOGM0NDM2NTQ3NjFjMDc4MjU2M2Q2ZTExZDllOTMyYzc5Y2FjY2Q5
-    NWNkNzAyOGRlNWVhN2ZmZTBhZmQ4YTJlYmM2YTVlODA3MWVhZTlmNjg1NGY2
-    NjkyOWZlZDZmMTI3MjFhYmNkYjNmMGE1MTc2NDdjYWU1N2ZlM2I=