knife-cookbook-doc 0.2.0

data/.gitignore

@@ -0,0 +1,9 @@
+/Gemfile.lock
+
+# Intermediate package dir
+/pkg
+
+# Ignore Intellij artifacts
+/*.iml
+/*.ipr
+/*.iws

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+v0.2.0 (Apr 1 2013)
+--------------------
+
+* Rework plugin to generate documentation for LWRPs.
+* Update the plugin to scan the source file for annotations to add to README.
+
+v0.1.1 (Feb 20 2013)
+--------------------
+
+* Convert plugin into a gem that can be installed via RubyGems.
+* Update README.
+* Add this CHANGELOG file.
+
+v0.1.0 (Dec 5 2012)
+-------------------
+
+* First tagged version.

data/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# How to Contribute
+
+Pull requests are greatly appreciated and are what makes opensource great. Here's a quick guide:
+
+* Fork it
+* Create your feature branch (`git checkout -b my-new-feature`)
+* Commit your changes (`git commit -am 'Add some feature'`)
+* Push to the branch (`git push origin my-new-feature`)
+* Create new Pull Request
+
+Pester us if we don't get your Pull Requests merged in a timely fashion. :)
+
+## How to speed the merging of pull requests
+
+* Describe your changes in the CHANGELOG. 
+* Give yourself some credit in the appropriate place (usually the CHANGELOG).
+* Make commits of logical units.
+* Ensure your commit messages help others understand what you are doing and why.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Maintain the same code style.
+* Maintain the same level of test coverage or improve it.
+
+## Additional Resources
+
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org/'
+
+gemspec

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,130 @@
+# knife-cookbook-doc
+
+This is a knife plugin to help create and maintain a README.md for a cookbook.
+As much as possible the plugin makes use of the same metadata as used by chef
+when generating the documentation. The plugin will also scan the source files
+for annotations present in comments. Users can also add fragments of markdown
+into the doc/ directory to merge into the generated README.md file.
+
+The goal is to keep the code as the authoritative source of information. The
+hope is that keeping the documentation close to the code will help to maintain
+it's currency.
+
+## Getting Started
+
+#### Step 1
+
+Populate the `metadata.rb` of your cookbook according to Opscode's
+[documentation](http://docs.opscode.com/config_rb_metadata.html). Particular
+attention should be paid to documenting the recipes, attributes, platform
+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;
+
+    =begin
+    #<
+    The recipe is awesome. It does thing 1, thing 2 and thing 3!
+    #>
+    =end
+
+#### Step 3
+
+In each LWRP, add detailed documentation such as;
+
+    =begin
+    #<
+    This creates and destroy the awesome service.
+
+    @action create  Create the awesome service.
+    @action destroy Destroy the awesome service.
+
+    @section Examples
+
+        # An example of my awesome service
+        mycookbook_awesome_service "my_service" do
+          port 80
+        end
+    #>
+    =end
+
+    ...
+
+    #<> @attribute port The port on which the HTTP service will bind.
+    attribute :port, :kind_of => Integer, :default => 8080
+
+It should be noted that the documentation of the LWRP requires that the user
+document the actions, using `@action <action> <description>` and the attributes
+using `@attribute <attribute> <description>` so that there is meaningful
+descriptions for the actions and attributes in the generated README.
+
+The documentation will be added at the start of the LWRP documentation
+except if marked with `@section <heading>`, in which case it will be added
+to the head of the LWRP documentation.
+
+#### Step 4
+
+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.
+
+## Installation
+
+You can install the plugin via RubyGems:
+
+    $ gem install knife-cookbook-doc
+
+Alternatively, you can install the plugin from source:
+
+    $ git clone git://github.com/realityforge/knife-cookbook-doc.git
+    $ cd knife-cookbook-doc/
+    $ bundle install
+    $ bundle exec rake install
+
+Afterwards, the new knife command `knife cookbook doc DIR` will be available.
+
+## Usage
+
+    knife cookbook doc COOKBOOK_DIR (options)
+
+        -o, --output-file FILE           Set the output file to render to relative to cookbook dir. Defaults to README.md
+        -t, --template FILE              Set template file used to render README.md
+
+    Examples:
+
+        knife cookbook doc path/to/cookbook
+        knife cookbook doc path/to/cookbook --template README.md.erb
+
+## Further Details
+
+### Documentation in comments
+
+The documentation stored in comments comes in three forms;
+
+#### Single line comments
+
+    #<> This is some documentation
+
+#### Multi-line comments using begin/end
+
+    =begin
+    #<
+    This is some documentation
+    #>
+    =end
+
+#### Multi-line comments without using begin/end
+
+    #<
+    # This is some documentation
+    #>
+
+
+## Credit
+
+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.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rake/clean'
+
+task :default => :build
+
+CLEAN.include 'pkg'

data/knife_cookbook_doc.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/knife_cookbook_doc/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.authors       = ['Mathias Lafeldt', 'Peter Donald']
+  s.email         = %w(mathias.lafeldt@gmail.com peter@realityforge.org)
+  s.description   = %q{Knife plugin to generate README.md for a cookbook}
+  s.summary       = s.description
+  s.homepage      = 'http://realityforge.github.com/knife-cookbook-doc'
+  s.license       = 'Apache 2.0'
+
+  s.files         = `git ls-files`.split($\)
+  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.name          = 'knife-cookbook-doc'
+  s.require_paths = %w(lib)
+  s.version       = KnifeCookbookDoc::VERSION
+
+  s.add_dependency 'chef'
+  s.add_dependency 'erubis'
+
+  s.add_development_dependency 'rake'
+end

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

@@ -0,0 +1,122 @@
+# Description
+
+<% unless fragments['overview'] -%>
+<%= description %>
+<% else -%>
+<%= fragments['overview'] -%>
+<% end -%>
+
+# Requirements
+
+## Platform:
+
+<% unless platforms.empty? %>
+<% platforms.each do |platform| %>
+* <%= platform %>
+<% end %>
+<% else %>
+*No platforms defined*
+<% end %>
+
+## Cookbooks:
+
+<% unless dependencies.empty? && recommendations.empty? && suggestions.empty? && conflicting.empty? %>
+<% dependencies.each do |cookbook| %>
+* <%= cookbook %>
+<% end %>
+<% recommendations.each do |cookbook| %>
+* <%= cookbook %> (Recommended but not required)
+<% end %>
+<% suggestions.each do |cookbook| %>
+* <%= cookbook %> (Suggested but not required)
+<% end %>
+<% conflicting.each do |cookbook| %>
+* Conflicts with <%= cookbook %>
+<% end %>
+<% else %>
+*No dependencies defined*
+<% end %>
+
+# Attributes
+
+<% unless attributes.empty? %>
+<% attributes.each do |name, description, default| %>
+* `<%= name %>` - <%= description %>. Defaults to `<%= default %>`.
+<% end %>
+<% else %>
+*No attributes defined*
+<% end %>
+
+# Recipes
+
+<% unless recipes.empty? %>
+<% recipes.each do |recipe| %>
+* <% if recipe.top_level_descriptions.empty? %><%= recipe.name %><% else %>[<%= recipe.name %>](#<%= recipe.name.gsub(':','') %>)<% end %><% if recipe.short_description != '' %> - <%= recipe.short_description %><% end %>
+<% end %>
+
+<% recipes.each do |recipe| -%>
+<% unless recipe.top_level_descriptions.empty? -%>
+## <%= recipe.name %>
+
+<% if recipe.top_level_description('main') != '' -%>
+<%= recipe.top_level_description('main') %>
+
+<% end -%>
+<% recipe.top_level_descriptions.keys.select{|k| k != 'main'}.each do |key| -%>
+### <%= key -%>
+
+<%= recipe.top_level_description(key) %>
+
+<% end -%>
+<% end -%>
+<% end -%>
+<% else -%>
+*No recipes defined*
+
+<% end -%>
+<% unless resources.empty? -%>
+# Resources
+
+<% resources.each do |resource| %>
+* [<%= resource.name %>](#<%= resource.name %>)<% if resource.short_description %> - <%= resource.short_description %><% end %>
+<% end %>
+
+<% resources.each do |resource| -%>
+## <%= resource.name %>
+
+<% if resource.top_level_description('main') != '' -%>
+<%= resource.top_level_description('main') -%>
+
+<% end -%>
+<% unless resource.actions.empty? -%>
+### Actions
+
+<% resource.actions.each do |action| -%>
+- <%= action %>: <%= resource.action_description(action) %><% if resource.default_action == action %> Default action.<% end %>
+<% end -%>
+<% end -%>
+<% unless resource.attributes.empty? -%>
+
+### Attribute Parameters
+
+<% resource.attributes.each do |attribute| -%>
+- <%= attribute %>: <%= resource.attribute_description(attribute) %><% if resource.attribute_has_default_value?(attribute) %> Defaults to <code><%= resource.attribute_default_value(attribute).inspect %></code>.<% end %>
+<% end -%>
+<% end -%>
+<% resource.top_level_descriptions.keys.select{|k| k != 'main'}.each do |key| -%>
+
+### <%= key -%>
+
+<%= resource.top_level_description(key) -%>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% fragments.keys.select {|k|k != 'overview'}.each do |key| -%>
+<%= fragments[key] %>
+<% end -%>
+# License and Maintainer
+
+Maintainer:: <%= maintainer %> (<<%= maintainer_email %>>)
+
+License:: <%= license %>

data/lib/chef/knife/cookbook_doc.rb

@@ -0,0 +1,52 @@
+require 'chef/knife'
+require 'pathname'
+
+module KnifeCookbookDoc
+  class CookbookDoc < Chef::Knife
+    deps do
+      require 'chef/cookbook/metadata'
+      require 'erubis'
+      require 'knife_cookbook_doc/readme_model'
+      require 'knife_cookbook_doc/recipe_model'
+      require 'knife_cookbook_doc/resource_model'
+    end
+
+    banner 'knife cookbook doc DIR (options)'
+
+    option :constraints,
+           :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',
+           :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,
+           :description => 'Set template file used to render README.md'
+
+    def run
+      unless (cookbook_dir = name_args.first)
+        ui.fatal 'Please provide cookbook directory as an argument'
+        exit(1)
+      end
+
+      model = ReadmeModel.new(cookbook_dir, config[:constraints])
+
+      template = File.read(config[:template_file])
+      eruby = Erubis::Eruby.new(template)
+      result = eruby.result(model.get_binding)
+
+      File.open("#{cookbook_dir}/#{config[:output_file]}",'wb') do |f|
+        f.write result
+      end
+    end
+  end
+end

data/lib/knife_cookbook_doc/readme_model.rb

@@ -0,0 +1,107 @@
+module KnifeCookbookDoc
+  class ReadmeModel
+    DEFAULT_CONSTRAINT = ">= 0.0.0".freeze
+
+    def initialize(cookbook_dir, constraints)
+
+      @metadata = Chef::Cookbook::Metadata.new
+      @metadata.from_file("#{cookbook_dir}/metadata.rb")
+
+      @resources = []
+      Dir["#{cookbook_dir}/resources/*.rb"].sort.each do |resource_filename|
+        @resources << ResourceModel.new(@metadata.name, resource_filename)
+      end
+
+      @fragments = {}
+      Dir["#{cookbook_dir}/doc/*.md"].sort.each do |resource_filename|
+        @fragments[::File.basename(resource_filename,'.md')] = IO.read(resource_filename)
+      end
+
+      @recipes = []
+      @metadata.recipes.each do |name, description|
+        @recipes << RecipeModel.new(name, description, "#{cookbook_dir}/recipes/#{name.gsub(/^.*\:(.*)$/,'\1')}.rb")
+      end
+      @metadata = @metadata
+      @constraints = constraints
+    end
+
+    def fragments
+      @fragments
+    end
+
+    def resources
+      @resources
+    end
+
+    def description
+      @metadata.description
+    end
+
+    def platforms
+      @metadata.platforms.map do |platform, version|
+        format_constraint(platform.capitalize, version)
+      end
+    end
+
+    def dependencies
+      @metadata.dependencies.map do |cookbook, version|
+        format_constraint(cookbook, version)
+      end
+    end
+
+    def recommendations
+      @metadata.recommendations.map do |cookbook, version|
+        format_constraint(cookbook, version)
+      end
+    end
+
+    def suggestions
+      @metadata.suggestions.map do |cookbook, version|
+        format_constraint(cookbook, version)
+      end
+    end
+
+    def conflicting
+      @metadata.conflicting.map do |cookbook, version|
+        format_constraint(cookbook, version)
+      end
+    end
+
+    def attributes
+      @metadata.attributes.map do |attr, options|
+        name = "node['#{attr.gsub("/", "']['")}']"
+        [name, options['description'], options['default']]
+      end
+    end
+
+    def recipes
+      @recipes
+    end
+
+    def maintainer
+      @metadata.maintainer
+    end
+
+    def maintainer_email
+      @metadata.maintainer_email
+    end
+
+    def license
+      @metadata.license
+    end
+
+    def get_binding
+      binding
+    end
+
+    private
+
+    def format_constraint(name, version)
+      if @constraints && version != DEFAULT_CONSTRAINT
+        "#{name} (#{version})"
+      else
+        name
+      end
+    end
+  end
+end

data/lib/knife_cookbook_doc/recipe_model.rb

@@ -0,0 +1,77 @@
+module KnifeCookbookDoc
+  class RecipeModel
+
+    attr_reader :name
+    attr_reader :short_description
+
+    def initialize(name, short_description, filename)
+      @name = name
+      @short_description = short_description
+      @filename = filename
+      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
+      current_section = 'main'
+      extract_description.each_line do |line|
+        if /^ *\@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
+    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
+  end
+
+  class DocumentingLWRPBase < ::Chef::Resource::LWRPBase
+
+    class << self
+      def attribute_specifications
+        @attribute_specifications ||= {}
+      end
+
+      def desc(description)
+        @description = "#{@description}#{description}\n"
+      end
+
+      def description
+        @description || ""
+      end
+    end
+
+    def self.attribute(attr_name, validation_opts={})
+      result = super(attr_name, validation_opts)
+      attribute_specifications[attr_name] = validation_opts
+      result
+    end
+  end
+end

data/lib/knife_cookbook_doc/resource_model.rb

@@ -0,0 +1,147 @@
+module KnifeCookbookDoc
+  class ResourceModel
+
+    attr_reader :native_resource
+
+    def initialize(cookbook_name, file)
+      @native_resource = build_native_from_file(cookbook_name, file)
+      load_descriptions
+    end
+
+    def name
+      @native_resource.resource_name
+    end
+
+    # Return the unique set of actions, with the default one first, if there is a default
+    def actions
+      unless @actions
+        @actions = [default_action].compact + @native_resource.actions.sort.uniq.select { |a| a != default_action }
+      end
+      @actions
+    end
+
+    def default_action
+      @native_resource.default_action
+    end
+
+    def action_description(action)
+      action_descriptions[action.to_s]
+    end
+
+    def action_descriptions
+      @action_descriptions ||= {}
+    end
+
+    def attributes
+      @native_resource.attribute_specifications.keys
+    end
+
+    def attribute_description(attribute)
+      attribute_descriptions[attribute.to_s]
+    end
+
+    def attribute_has_default_value?(attribute)
+      specification = @native_resource.attribute_specifications[attribute]
+      specification && specification.has_key?(:default)
+    end
+
+    def attribute_default_value(attribute)
+      if attribute_has_default_value?(attribute)
+        return @native_resource.attribute_specifications[attribute][:default]
+      else
+        return nil
+      end
+    end
+
+    def attribute_descriptions
+      @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(/^([^.]*?\.)/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
+      current_section = 'main'
+      @native_resource.description.each_line do |line|
+        if /^ *\@action *([^ ]*) (.*)$/ =~ line
+          action_descriptions[$1] = $2.strip
+        elsif /^ *\@attribute *([^ ]*) (.*)$/ =~ line
+          attribute_descriptions[$1] = $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
+    end
+
+    include ::Chef::Mixin::ConvertToClassName
+
+    def build_native_from_file(cookbook_name, filename)
+      resource_class = Class.new(DocumentingLWRPBase)
+
+      resource_class.resource_name = filename_to_qualified_string(cookbook_name, filename)
+      resource_class.run_context = nil
+      resource_data = IO.read(filename)
+      resource_data = resource_data.gsub(/^=begin *\n *\#\<\n(.*?)^ *\#\>\n=end *\n/m) do
+        "desc <<DOCO\n#{$1}\nDOCO\n"
+      end
+      resource_data = resource_data.gsub(/^ *\#\<\n(.*?)^ *\#\>\n/m) do
+        "desc <<DOCO\n#{$1.gsub(/^ *\# ?/, '')}\nDOCO\n"
+      end
+      resource_data = resource_data.gsub(/^ *\#\<\> (.*?)$/) do
+        "desc #{$1.inspect}\n"
+      end
+
+      resource_class.class_eval(resource_data, filename, 1)
+
+      resource_class
+    end
+  end
+
+  class DocumentingLWRPBase < ::Chef::Resource::LWRPBase
+
+    class << self
+      def attribute_specifications
+        @attribute_specifications ||= {}
+      end
+
+      def desc(description)
+        @description = "#{@description}#{description}\n"
+      end
+
+      def description
+        @description || ""
+      end
+    end
+
+    def self.attribute(attr_name, validation_opts={})
+      result = super(attr_name, validation_opts)
+      attribute_specifications[attr_name] = validation_opts
+      result
+    end
+  end
+end

data/lib/knife_cookbook_doc/version.rb

@@ -0,0 +1,3 @@
+module KnifeCookbookDoc
+  VERSION = '0.2.0'
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: knife-cookbook-doc
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Mathias Lafeldt
+- Peter Donald
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chef
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: erubis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Knife plugin to generate README.md for a cookbook
+email:
+- mathias.lafeldt@gmail.com
+- peter@realityforge.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- knife_cookbook_doc.gemspec
+- lib/chef/knife/README.md.erb
+- lib/chef/knife/cookbook_doc.rb
+- lib/knife_cookbook_doc/readme_model.rb
+- lib/knife_cookbook_doc/recipe_model.rb
+- lib/knife_cookbook_doc/resource_model.rb
+- lib/knife_cookbook_doc/version.rb
+homepage: http://realityforge.github.com/knife-cookbook-doc
+licenses:
+- Apache 2.0
+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: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Knife plugin to generate README.md for a cookbook
+test_files: []