knife-cookbook-doc 0.27.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5ef732bc170168616bfc22e319838395fdfd789a
-  data.tar.gz: 2b933a18b2825171e52a6dbdf992a4e0b08c1c56
+SHA256:
+  metadata.gz: 32146e1b9e4922d6ad79b91e13b265644ab5d015f0c5cbdb3ee19cbc41d7e3da
+  data.tar.gz: 7b743e9a1dd63eb357f54bc3713c81c902f86f740163da01456cf7035b481913
 SHA512:
-  metadata.gz: 93bcc31a7e09ac48f3326b2c4ec3d29f1485be5518ca89f7d69a7ec406373ca392a19985709a9932ea02c2b633fd40ad1480256bbe5a91ca4f4b634febbde8df
-  data.tar.gz: 9ddb6f35e8ceb8fa57b050195c11a611cb5bb731e7ad03f382689c395f1b47f9d8e9b8e403dd1a579315b39e8e159ce60799138ed69d5fb3b5ab2dc4d9cad2b9
+  metadata.gz: b53f6f936367ddd06a000582f7c7e7f8aed90b277854d579933abbb31b2476920d9f9bb5fd1b9991ec25164dd2325c88feeb6db35225390b76a86fea5fc43d23
+  data.tar.gz: 4cd5dff63120570a7ecfe3bb5da66fab1d2918c41f5b7c1334fc6e31d7048ada30678a9b8e17cd96527420bed0346c522d4165b5e23c9b6fed3ea479e54afe17

data/.gitignore

@@ -1,5 +1,6 @@
 /Gemfile.lock
 /*.gem
+/fixture/README-generated.md
 
 # Intermediate package dir
 /pkg

data/.travis.yml

@@ -5,33 +5,83 @@ gemfile: fixture/gemfile
 rvm:
   - 2.2.6
   - 2.3.3
+  - 2.6.7
+  - 2.7.3
 
 env:
-  - CHEF_VERSION=master
-  - CHEF_VERSION=12.5.1
-  - CHEF_VERSION=12.4.1
-  - CHEF_VERSION=12.3.0
-  - CHEF_VERSION=12.2.1
-  - CHEF_VERSION=12.1.2
-  - CHEF_VERSION=12.0.3
-  - CHEF_VERSION=11.18.12
-  - CHEF_VERSION=11.16.4
-  - CHEF_VERSION=11.14.6
-  - CHEF_VERSION=11.12.8
-  - CHEF_VERSION=11.10.4
+  - CHEF_VERSION=master EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+  - CHEF_VERSION=16.13.16 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+  - CHEF_VERSION=15.17.4 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+  - CHEF_VERSION=12.6.0 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+  - CHEF_VERSION=12.5.1 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=12.4.1 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=12.3.0 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=12.2.1 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=12.1.2 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=12.0.3 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=11.18.12 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=11.16.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=11.14.6 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=11.12.8 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+  - CHEF_VERSION=11.10.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
 
 matrix:
   fast_finish: true
   exclude:
-    - env: CHEF_VERSION=11.12.8
+    - env: CHEF_VERSION=11.12.8 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
       rvm: 2.3.3
-    - env: CHEF_VERSION=11.10.4
+    - env: CHEF_VERSION=11.10.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
       rvm: 2.3.3
+    # As of May 28 2021, chef/chef master requires 2.7 or higher
+    - env: CHEF_VERSION=master EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.2.6
+    - env: CHEF_VERSION=master EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.3.3
+    - env: CHEF_VERSION=master EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.6.7
+    # Newer Chef does not work with old Ruby
+    - env: CHEF_VERSION=16.13.16 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.2.6
+    - env: CHEF_VERSION=15.17.4 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.2.6
+    - env: CHEF_VERSION=16.13.16 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.3.3
+    - env: CHEF_VERSION=15.17.4 EXPECTED_FILE=README-expected.md METADATA=metadata.rb
+      rvm: 2.3.3
+    # Old Chef bundles old json package incompatible with newer Ruby
+    - env: CHEF_VERSION=12.1.2 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=12.1.2 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=12.0.3 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=12.0.3 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=11.18.12 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=11.18.12 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=11.16.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=11.16.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=11.14.6 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=11.14.6 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=11.12.8 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=11.12.8 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
+    - env: CHEF_VERSION=11.10.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.6.7
+    - env: CHEF_VERSION=11.10.4 EXPECTED_FILE=README-expected_legacy.md METADATA=metadata_legacy.rb
+      rvm: 2.7.3
 
   allow_failures:
-    - env: CHEF_VERSION=master
+    - env: CHEF_VERSION=master EXPECTED_FILE=README-expected.md METADATA=metadata.rb
 
 script:
   - cd fixture
-  - bundle exec knife cookbook doc . -o README-generated.md -c knife.rb
-  - diff README-expected.md README-generated.md && rm README-generated.md
+  - bundle exec knife cookbook doc . -o README-generated.md -c knife.rb --metadata $METADATA
+  - diff $EXPECTED_FILE README-generated.md && rm README-generated.md

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+# v0.31.0 (Feb 7 2022)
+
+* Prettify Chef version constraints.
+
+# v0.30.0 (Mar 19 2021)
+
+* Support a space after # in custom resource. Submitted by Tomoya Kabe.
+
+# v0.29.0 (Jun 26 2020)
+
+* Extract descriptions from `libraries/*.rb`. Submitted by Joe Nuspl.
+
+# v0.28.0 (Jun 11 2020)
+
+* If `Berksfile` exists, add source_url links to cookbooks. Submitted by Joe Nuspl.
+
 # v0.27.0 (Jun 20 2019)
 
 * Add support for Chef 15. Submitted by grozan.

data/Rakefile

@@ -4,3 +4,12 @@ require 'rake/clean'
 task :default => :build
 
 CLEAN.include 'pkg'
+
+task :test => :install
+task :test do
+  sh <<SCRIPT
+cd fixture
+knife cookbook doc . -o README-generated.md -c knife.rb
+diff -u README-expected.md README-generated.md && rm README-generated.md
+SCRIPT
+end

data/fixture/README-expected.md

@@ -9,7 +9,8 @@
 
 ## Chef Client:
 
-*No Chef versions defined*
+* chef (>= 14.0, < 16.0)
+* chef (= 12.0)
 
 ## Platform:
 
@@ -36,6 +37,7 @@ MyApp Admin Group: The group allowed to manage MyApp.
 # Resources
 
 * [fixture](#fixture) - This resource is awesome.
+* [fixture_space](#fixture_space) - This resource is spacial.
 
 ## fixture
 
@@ -50,6 +52,24 @@ This resource is awesome.
 - my_attribute: This is an attribute. Defaults to <code>"a default value"</code>.
 - my_property: This is a property. Defaults to <code>"another default value"</code>.
 
+## fixture_space
+
+This resource is spacial.
+
+### Actions
+
+- stuff: Inserts spaces. Default action.
+
+### Attribute Parameters
+
+- my_attribute: This is an attribute. Defaults to <code>"a default value"</code>.
+- my_property: This is a property. Defaults to <code>"another default value"</code>.
+
+# Libraries
+
+## stooges()
+Returns `['Moe', 'Larry', 'Curly']`
+
 # Credits
 
 * Mathias Lafeldt

data/fixture/README-expected_legacy.md

@@ -0,0 +1,75 @@
+# Description
+
+# My Cookbook Readme
+
+**`knife cookbook doc .` _rocks_**
+
+# Requirements
+
+
+## Chef Client:
+
+*No Chef versions defined*
+
+## Platform:
+
+* cookbook-authors
+
+## Cookbooks:
+
+* upon-magic
+
+# Attributes
+
+* `node['knife']['cookbook']['doc']` -  Defaults to `successful automation`.
+
+# Recipes
+
+* [fixture::default](#fixturedefault) - The recipe is awesome.
+
+## fixture::default
+
+The recipe is awesome. It does thing 1, thing 2 and thing 3!
+
+MyApp Admin Group: The group allowed to manage MyApp.
+
+# Resources
+
+* [fixture](#fixture) - This resource is awesome.
+* [fixture_space](#fixture_space) - This resource is spacial.
+
+## fixture
+
+This resource is awesome.
+
+### Actions
+
+- stuff: Does awesome things. Default action.
+
+### Attribute Parameters
+
+- my_attribute: This is an attribute. Defaults to <code>"a default value"</code>.
+- my_property: This is a property. Defaults to <code>"another default value"</code>.
+
+## fixture_space
+
+This resource is spacial.
+
+### Actions
+
+- stuff: Inserts spaces. Default action.
+
+### Attribute Parameters
+
+- my_attribute: This is an attribute. Defaults to <code>"a default value"</code>.
+- my_property: This is a property. Defaults to <code>"another default value"</code>.
+
+# Libraries
+
+## stooges()
+Returns `['Moe', 'Larry', 'Curly']`
+
+# Credits
+
+* Mathias Lafeldt
+* Peter Donald

data/fixture/gemfile

@@ -2,6 +2,7 @@ source 'https://rubygems.org/'
 
 if ENV['CHEF_VERSION'] == 'master'
   gem 'chef', github: 'chef/chef'
+  gem 'knife', github: 'chef/chef'
 else
   gem 'chef', ENV['CHEF_VERSION']
 end

data/fixture/libraries/default.rb

@@ -0,0 +1,7 @@
+# <
+# ## stooges()
+# Returns `['Moe', 'Larry', 'Curly']`
+# >
+def stooges
+  %w(Moe Larry Curly)
+end

data/fixture/metadata.rb

@@ -5,6 +5,8 @@ license          'MIT'
 description      'Installs/Configures fixture'
 long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
 version          '0.1.0'
+chef_version     '>= 14.0', '< 16.0'
+chef_version     '= 12.0'
 
 supports 'cookbook-authors'
 depends 'upon-magic'

data/fixture/metadata_legacy.rb

@@ -0,0 +1,10 @@
+name             'fixture'
+maintainer       'A Cookbook Author'
+maintainer_email 'author@example.com'
+license          'MIT'
+description      'Installs/Configures fixture'
+long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
+version          '0.1.0'
+
+supports 'cookbook-authors'
+depends 'upon-magic'

data/fixture/resources/space.rb

@@ -0,0 +1,13 @@
+# <
+# This resource is spacial.
+#
+# @action stuff Inserts spaces.
+# >
+
+default_action :stuff
+
+# <> @attribute my_attribute This is an attribute.
+attribute :my_attribute, default: 'a default value'
+
+# <> @property my_property This is a property.
+property :my_property, default: 'another default value'

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

@@ -157,6 +157,13 @@
 <%= resource.top_level_description(key) -%>
 <% end -%>
 
+<% end -%>
+<% end -%>
+<% unless libraries.empty? -%>
+# Libraries
+<% libraries.each do |lib| -%>
+
+<%= lib.descriptions %>
 <% end -%>
 <% end -%>
 <% fragments.keys.select {|k|k != 'overview' && k != 'credit' && k != 'requirements'}.each do |key| -%>

data/lib/chef/knife/cookbook_doc.rb

@@ -9,6 +9,7 @@ module KnifeCookbookDoc
       require 'knife_cookbook_doc/base_model'
       require 'knife_cookbook_doc/documenting_lwrp_base'
       require 'knife_cookbook_doc/definitions_model'
+      require 'knife_cookbook_doc/libraries_model'
       require 'knife_cookbook_doc/readme_model'
       require 'knife_cookbook_doc/recipe_model'
       require 'knife_cookbook_doc/resource_model'
@@ -42,6 +43,11 @@ module KnifeCookbookDoc
            :default => false,
            :description => 'Ignore attributes without documetation'
 
+    option :metadata,
+           :long => '--metadata FILE',
+           :default => 'metadata.rb',
+           :description => 'metadata.rb path'
+
     def run
       unless (cookbook_dir = name_args.first)
         ui.fatal 'Please provide cookbook directory as an argument'

data/lib/knife_cookbook_doc/libraries_model.rb

@@ -0,0 +1,13 @@
+module KnifeCookbookDoc
+  class LibrariesModel
+    include KnifeCookbookDoc::BaseModel
+
+    attr_reader :descriptions
+
+    def initialize(name, filename)
+      @name = name
+      @filename = filename
+      @descriptions = extract_description
+    end
+  end
+end

data/lib/knife_cookbook_doc/rake_task.rb

@@ -6,6 +6,7 @@ require 'rake/tasklib'
 require 'knife_cookbook_doc/base_model'
 require 'knife_cookbook_doc/documenting_lwrp_base'
 require 'knife_cookbook_doc/definitions_model'
+require 'knife_cookbook_doc/libraries_model'
 require 'knife_cookbook_doc/readme_model'
 require 'knife_cookbook_doc/recipe_model'
 require 'knife_cookbook_doc/resource_model'

data/lib/knife_cookbook_doc/readme_model.rb

@@ -1,11 +1,19 @@
+begin
+  require 'berkshelf'
+rescue LoadError
+  # won't be able to get :source_url for dependent cookbooks
+end
+
 module KnifeCookbookDoc
   class ReadmeModel
     DEFAULT_CONSTRAINT = ">= 0.0.0".freeze
 
+    attr_reader :libraries
+
     def initialize(cookbook_dir, config)
 
       @metadata = Chef::Cookbook::Metadata.new
-      @metadata.from_file("#{cookbook_dir}/metadata.rb")
+      @metadata.from_file("#{cookbook_dir}/#{config[:metadata]}")
 
       if (!@metadata.attributes.empty? rescue false)
         @attributes = @metadata.attributes.map do |attr, options|
@@ -22,6 +30,10 @@ module KnifeCookbookDoc
         end
       end
 
+      @libraries = Dir["#{cookbook_dir}/libraries/*.rb"].sort.map do |path|
+        LibrariesModel.new(@metadata.name, path)
+      end
+
       @resources = []
       Dir["#{cookbook_dir}/resources/*.rb"].sort.each do |resource_filename|
         @resources << ResourceModel.new(@metadata.name, resource_filename)
@@ -98,8 +110,9 @@ module KnifeCookbookDoc
 
     def chef_versions
       if @metadata.methods.include?(:chef_version)
-        @metadata.chef_versions.map do |chef_version, version|
-          format_constraint(chef_version, version)
+        @metadata.chef_versions.map do |chef_version|
+          constraints = chef_version.requirements_list.join(', ')
+          format_constraint(chef_version.name, constraints)
         end
       else
         []
@@ -172,7 +185,28 @@ module KnifeCookbookDoc
 
     private
 
+    def source_url_from_berkshelf(name)
+      @source_url ||= begin
+        if File.exist?('Berksfile') && defined?(::Berkshelf)
+          ::Berkshelf::Berksfile
+            .from_file('Berksfile')
+            .install
+            .map { |cb| [cb.cookbook_name, cb.metadata.source_url] }
+            .to_h
+        else
+          {}
+        end
+      end
+      @source_url[name]
+    end
+
     def format_constraint(name, version)
+      url = source_url_from_berkshelf(name)
+      if !url.nil? && url.start_with?('http')
+        # git:// and ssh:// URLs are not browsable
+        name = "[#{name}](#{url})"
+      end
+
       if @constraints && version != DEFAULT_CONSTRAINT
         "#{name} (#{version})"
       else

data/lib/knife_cookbook_doc/resource_model.rb

@@ -98,13 +98,13 @@ module KnifeCookbookDoc
       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
+      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
+      resource_data = resource_data.gsub(/^ *\# ?\<\n(.*?)^ *\# ?\>\n/m) do
         "desc <<DOCO\n#{$1.gsub(/^ *\# ?/, '')}\nDOCO\n"
       end
-      resource_data = resource_data.gsub(/^ *\#\<\> (.*?)$/) do
+      resource_data = resource_data.gsub(/^ *\# ?\<\> (.*?)$/) do
         "desc #{$1.inspect}\n"
       end
 

data/lib/knife_cookbook_doc/version.rb

@@ -1,3 +1,3 @@
 module KnifeCookbookDoc
-  VERSION = '0.27.0'
+  VERSION = '0.31.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: knife-cookbook-doc
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Mathias Lafeldt
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-19 00:00:00.000000000 Z
+date: 2022-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef
@@ -88,15 +88,19 @@ files:
 - Rakefile
 - fixture/CHANGELOG.md
 - fixture/README-expected.md
+- fixture/README-expected_legacy.md
 - fixture/README.md
 - fixture/attributes/default.rb
 - fixture/doc/credit.md
 - fixture/doc/overview.md
 - fixture/gemfile
 - fixture/knife.rb
+- fixture/libraries/default.rb
 - fixture/metadata.rb
+- fixture/metadata_legacy.rb
 - fixture/recipes/default.rb
 - fixture/resources/default.rb
+- fixture/resources/space.rb
 - knife_cookbook_doc.gemspec
 - lib/chef/knife/README.md.erb
 - lib/chef/knife/cookbook_doc.rb
@@ -104,6 +108,7 @@ files:
 - 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/libraries_model.rb
 - lib/knife_cookbook_doc/rake_task.rb
 - lib/knife_cookbook_doc/readme_model.rb
 - lib/knife_cookbook_doc/recipe_model.rb
@@ -130,8 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Knife plugin to generate README.md for a cookbook