knife-cookbook-doc 0.3.0 → 0.5.0

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+v0.5.0 (Sep 16 2013)
+--------------------
+
+* Re-push gem with correct set of changes to rubygems.
+
+v0.4.0 (Sep 16 2013)
+--------------------
+
+* Scan the recipes directory for recipes if no recipes are declared in the metadata.rb (Skipping recipes with a name starting with '_'). Submitted by Jarek Gawor.
+* Scan the attributes files if no attributes are declared in the metadata.rb and collect descriptions from comments. Submitted by Jarek Gawor.
+* Descriptions scanned from source files should expect the . separator to be followed by a space. Submitted by Jarek Gawor.
+
+v0.3.0 (Apr 1 2013)
+--------------------
+
+* Replace the last section of the readme with the doc/credit.md fragment if it is present.
+
 v0.2.0 (Apr 1 2013)
 --------------------
 

data/README.md

@@ -21,7 +21,7 @@ compatibility and cookbook requirements (i.e. depends, recommends, suggests etc)
 
 #### Step 2
 
-At the top of each cookbook, add a detailed documentation section such as;
+At the top of each recipe, add a detailed documentation section such as;
 
     =begin
     #<
@@ -67,8 +67,10 @@ to the end of the LWRP documentation.
 
 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. The remaining fragments will be included
-at the end of the readme in lexicographic order of the filename.
+`Description` section of the readme. You should also add a `doc/credit.md` which
+will replace the last 'License and Maintainer' section in the readme. The
+remaining fragments will be included at the end of the readme in lexicographic
+order of the filename.
 
 ## Installation
 
@@ -127,4 +129,5 @@ The documentation stored in comments comes in three forms;
 The plugin was originally written by Mathias Lafeldt as a way to create
 initial README.md from the metadata.rb. It was subsequently rewritten by
 Peter Donald to gather information from the other files within the cookbook.
-All credit to Mathias for his wonderful idea.
+All credit to Mathias for his wonderful idea. Jarek Gawor has also submitted
+several major changes.

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

@@ -40,8 +40,8 @@
 # Attributes
 
 <% unless attributes.empty? %>
-<% attributes.each do |name, description, default| %>
-* `<%= name %>` - <%= description %>. Defaults to `<%= default %>`.
+<% attributes.each do |name, description, default, choice| %>
+* `<%= name %>` - <%= description %><% if !description.nil? && !description.strip.end_with?(".") %>.<% end %> <% unless choice.empty? %>Available options: <%= "`#{choice.join('`, `')}`" %>. <% end %>Defaults to `<%= default %>`.
 <% end %>
 <% else %>
 *No attributes defined*

data/lib/chef/knife/cookbook_doc.rb

@@ -9,6 +9,7 @@ module KnifeCookbookDoc
       require 'knife_cookbook_doc/readme_model'
       require 'knife_cookbook_doc/recipe_model'
       require 'knife_cookbook_doc/resource_model'
+      require 'knife_cookbook_doc/attributes_model'
     end
 
     banner 'knife cookbook doc DIR (options)'

data/lib/knife_cookbook_doc/attributes_model.rb

@@ -0,0 +1,64 @@
+module KnifeCookbookDoc
+  class AttributesModel
+
+    ATTRIBUTE_REGEX = "(^\s*default.*?)=(.*?)$".freeze
+
+    def initialize(filename)
+      @filename = filename
+      @attributes = {}
+      load_descriptions
+    end
+
+    def attributes
+      @attributes.map do |name, options|
+        [name, options[:description], options[:default], []]
+      end
+    end
+
+    private
+
+    def load_descriptions
+      resource_data = IO.read(@filename)
+
+      # find all attributes
+      resource_data.gsub(/#{ATTRIBUTE_REGEX}/) do
+        name = get_attribute_name($1)
+        value = $2.strip
+
+        if value.starts_with?("{")
+          value = "{ ... }"
+        elsif  value.starts_with?("[") 
+          value = "[ ... ]"
+        else
+          value = value.gsub(/\A\"|\A'|\"\Z|'\Z/, '')
+        end
+        
+        options = {}
+        options[:default] = value
+        @attributes[name] = options
+      end
+
+      # get/parse comments
+      resource_data = resource_data.gsub(/^=begin\s*\n\s*\#\<\s*\n(.*?)^\s*\#\>\n=end\s*\n#{ATTRIBUTE_REGEX}/m) do
+        update_attribute($2, $1)
+      end
+      resource_data = resource_data.gsub(/^\s*\#\<\n(.*?)^\s*\#\>\n#{ATTRIBUTE_REGEX}/m) do
+        update_attribute($2, $1.gsub(/^\s*\# ?/, ''))
+      end
+      resource_data = resource_data.gsub(/^\s*\#\<\>\s(.*?$)\n#{ATTRIBUTE_REGEX}/m) do
+        update_attribute($2, $1)
+      end
+    end
+
+    def update_attribute(name, description) 
+      name = get_attribute_name(name)
+      options = @attributes[name]
+      options[:description] = description.strip
+    end
+
+    def get_attribute_name(name)
+      name.strip.gsub(/^default/, "node")
+    end
+
+  end
+end

data/lib/knife_cookbook_doc/readme_model.rb

@@ -7,6 +7,21 @@ module KnifeCookbookDoc
       @metadata = Chef::Cookbook::Metadata.new
       @metadata.from_file("#{cookbook_dir}/metadata.rb")
 
+      if !@metadata.attributes.empty?
+        @attributes = @metadata.attributes.map do |attr, options|
+          name = "node['#{attr.gsub("/", "']['")}']"
+          [name, options['description'], options['default'], options['choice']]
+        end
+      else
+        @attributes = []
+        Dir["#{cookbook_dir}/attributes/*.rb"].sort.each do |attribute_filename|
+          model = AttributesModel.new(attribute_filename)
+          if !model.attributes.empty?
+            @attributes += model.attributes
+          end
+        end        
+      end
+
       @resources = []
       Dir["#{cookbook_dir}/resources/*.rb"].sort.each do |resource_filename|
         @resources << ResourceModel.new(@metadata.name, resource_filename)
@@ -18,8 +33,17 @@ module KnifeCookbookDoc
       end
 
       @recipes = []
-      @metadata.recipes.each do |name, description|
-        @recipes << RecipeModel.new(name, description, "#{cookbook_dir}/recipes/#{name.gsub(/^.*\:(.*)$/,'\1')}.rb")
+      if !@metadata.recipes.empty?
+        @metadata.recipes.each do |name, description|
+          @recipes << RecipeModel.new(name, description, "#{cookbook_dir}/recipes/#{name.gsub(/^.*\:(.*)$/,'\1')}.rb")
+        end
+      else
+        Dir["#{cookbook_dir}/recipes/*.rb"].sort.each do |recipe_filename|
+          base_name = File.basename(recipe_filename, ".rb")
+          if !base_name.start_with?("_")
+            @recipes << RecipeModel.new("#{@metadata.name}::#{base_name}", recipe_filename)
+          end
+        end
       end
       @metadata = @metadata
       @constraints = constraints
@@ -68,10 +92,7 @@ module KnifeCookbookDoc
     end
 
     def attributes
-      @metadata.attributes.map do |attr, options|
-        name = "node['#{attr.gsub("/", "']['")}']"
-        [name, options['description'], options['default']]
-      end
+      @attributes
     end
 
     def recipes

data/lib/knife_cookbook_doc/recipe_model.rb

@@ -4,7 +4,7 @@ module KnifeCookbookDoc
     attr_reader :name
     attr_reader :short_description
 
-    def initialize(name, short_description, filename)
+    def initialize(name, short_description = nil, filename)
       @name = name
       @short_description = short_description
       @filename = filename
@@ -23,7 +23,8 @@ module KnifeCookbookDoc
 
     def load_descriptions
       current_section = 'main'
-      extract_description.each_line do |line|
+      description = extract_description
+      description.each_line do |line|
         if /^ *\@section (.*)$/ =~ line
           current_section = $1.strip
         else
@@ -32,6 +33,9 @@ module KnifeCookbookDoc
           top_level_descriptions[current_section] = lines
         end
       end
+      if @short_description.nil? 
+        @short_description = first_sentence(description) || ""
+      end
     end
 
     include ::Chef::Mixin::ConvertToClassName
@@ -50,6 +54,13 @@ module KnifeCookbookDoc
       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
 
   class DocumentingLWRPBase < ::Chef::Resource::LWRPBase

data/lib/knife_cookbook_doc/resource_model.rb

@@ -65,7 +65,7 @@ module KnifeCookbookDoc
     end
 
     def first_sentence(string)
-      string.gsub(/^([^.]*?\.)/m) do |match|
+      string.gsub(/^(.*?\.(\z|\s))/m) do |match|
         return $1.gsub("\n",' ').strip
       end
       return nil

data/lib/knife_cookbook_doc/version.rb

@@ -1,3 +1,3 @@
 module KnifeCookbookDoc
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: knife-cookbook-doc
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-02 00:00:00.000000000 Z
+date: 2013-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef
@@ -78,6 +78,7 @@ files:
 - knife_cookbook_doc.gemspec
 - lib/chef/knife/README.md.erb
 - lib/chef/knife/cookbook_doc.rb
+- lib/knife_cookbook_doc/attributes_model.rb
 - lib/knife_cookbook_doc/readme_model.rb
 - lib/knife_cookbook_doc/recipe_model.rb
 - lib/knife_cookbook_doc/resource_model.rb