knife-cookbook-doc 0.25.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bbbc143a652e8129c85a65adcf70802ae67bcbd0
-  data.tar.gz: 1630f21c869c7a02da034b4fc23057e0f16f3121
+  metadata.gz: 7d4e4e61d176043dd41fa77782ac36203bc1251a
+  data.tar.gz: 49a72076fe65ea3f15878479e7c709394e2bc14c
 SHA512:
-  metadata.gz: 26328bdf572cfc2b4585ce9ba1164420f3e530f225be7cbbfc37b4370c9dc4ce8a9dbe037b14d1968f948878602661ce48f5d9251bda5b720e69bcd7edb10259
-  data.tar.gz: 92b78ebc35f1e540e42b2b167149d529cdf3d42bf81ac94aec3f2b4c63fcb36088b50a47a11b14f2868df4d0cbcbaf9d512990966cef047cd94267dcdab2ce38
+  metadata.gz: 325f8c3e22e8f67778480106847aafbccc2d7da9d58831005f3fa09b7e3de3c4710c9a05e6023718a8669c064e51c94f3cc8cf5305752704e5d6a587d5c89fae
+  data.tar.gz: 876de6b5caff31196e93bd7dd71c8b5fb1c6bec5725a95c24644595ae19954de6a043d1e987be44df56c67c1e376eec46bec027bcd9ef285ce0b7393347e97da

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,47 @@
+<!--
+Thanks for your interest in the project. I appreciate bugs filed and PRs submitted!
+Please make sure that you are familiar with and follow the Code of Conduct for
+this project (found in the CODE_OF_CONDUCT.md file).
+
+Please fill out this template with all the relevant information so we can
+understand what's going on and fix the issue.
+
+I may ask you to submit the fix (after giving some direction).
+-->
+
+Environment:
+
+<!--
+  Please provide the version of this project where the issue occurred as well as the
+  versions of other environmental factors. This could be virtual machine version, os
+  version, browser version etc.
+-->
+
+Relevant code or config:
+
+```
+
+```
+
+What you did:
+
+
+
+What happened:
+
+<!-- Please provide the full error message/screenshots/anything -->
+
+Reproduction repository:
+
+<!--
+If possible, please create a repository that reproduces the issue with the
+minimal amount of code possible. It is highly recommended you take the time
+to read "How to create a Minimal, Complete, and Verifiable example" at
+https://stackoverflow.com/help/mcve
+-->
+
+Problem description:
+
+
+
+Suggested solution:

data/.gitignore

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

data/.travis.yml

@@ -1,6 +1,5 @@
 language: ruby
 cache: bundler
-sudo: false
 gemfile: fixture/gemfile
 
 rvm:

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+# 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.
+
+# v0.26.0 (Mar 4 2019)
+
+* Display `lazy` defaults as such. Submitted by Joe Nuspl.
+
+# v0.25.2 (Dec 18 2018)
+
+* Re-release gem with the appropriate version.
+
+# v0.24.2 (Dec 17 2018)
+
+* Add chef_versions support. Submitted by Nikolay Antsiferov.
+
+# v0.25.0 (Mar 7 2018)
+
+* Remove deprecated metadata for >= Chef 13. Submitted by Jamie Tanna.
+
 # v0.24.1 (Oct 2 2017)
 
 * Fix the markdown spacing for maintainer/source/issues URL. Submitted by Jamie Tanna.

data/CONTRIBUTING.md

@@ -1,19 +1,34 @@
 # How to Contribute
 
-Pull requests are greatly appreciated and are what makes opensource great. Here's a quick guide:
+We'd love to accept your patches and contributions to this project. Pull requests are part of
+what makes open source great. There are just a few small guidelines you need to follow.
 
-* 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
+## Code of Conduct
 
-Pester us if we don't get your Pull Requests merged in a timely fashion. :)
+Participation in this project comes under the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md)
+
+## Submitting code via Pull Requests
+
+- We follow the [Github Pull Request Model](https://help.github.com/articles/about-pull-requests/) for
+  all contributions.
+- For large bodies of work, we recommend creating an issue outlining the feature that you wish to build,
+  and describing how it will be implemented. This gives a chance for review to happen early, and ensures
+  no wasted effort occurs.
+- All submissions, will require review before being merged.
+- Finally - *Thanks* for considering submitting code to the project!
+
+## Formatting
+
+When submitting pull requests, make sure to do the following:
+
+- Maintain the same code style as the rest of the project.
+- Remove trailing whitespace. Many editors will do this automatically.
+- Ensure any new files have [a trailing newline](https://stackoverflow.com/questions/5813311/no-newline-at-end-of-file)
 
 ## 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).
+* Describe your changes in the CHANGELOG.md (if present).
+* Give yourself some credit in the appropriate place (usually the CHANGELOG.md).
 * 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.
@@ -23,4 +38,6 @@ Pester us if we don't get your Pull Requests merged in a timely fashion. :)
 ## Additional Resources
 
 * [General GitHub documentation](http://help.github.com/)
-* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+* [How to write a good Git Commit message](https://chris.beams.io/posts/git-commit/) -
+  Great way to make sure your Pull Requests get accepted.
+* [An Open Source Etiquette Guidebook](https://css-tricks.com/open-source-etiquette-guidebook/#article-header-id-1)

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

@@ -6,6 +6,11 @@
 
 # Requirements
 
+
+## Chef Client:
+
+*No Chef versions defined*
+
 ## Platform:
 
 * cookbook-authors
@@ -45,6 +50,11 @@ 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>.
 
+# Libraries
+
+## stooges()
+Returns `['Moe', 'Larry', 'Curly']`
+
 # Credits
 
 * Mathias Lafeldt

data/fixture/libraries/default.rb

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

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

@@ -12,6 +12,17 @@
 <%= fragments['requirements'] -%>
 
 <% end -%>
+
+## Chef Client:
+
+<% unless chef_versions.empty? %>
+<% chef_versions.each do |chef_version| %>
+* <%= chef_version %>
+<% end %>
+<% else %>
+*No Chef versions defined*
+<% end %>
+
 ## Platform:
 
 <% unless platforms.empty? %>
@@ -136,7 +147,7 @@
 ### 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 %>
+- <%= attribute %>: <%= resource.attribute_description(attribute) %><% if resource.attribute_has_default_value?(attribute) %> Defaults to <code><%= resource.attribute_default_value(attribute) %></code>.<% end %>
 <% end -%>
 <% end -%>
 <% resource.top_level_descriptions.keys.select{|k| k != 'main'}.each do |key| -%>
@@ -146,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'

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,13 +1,21 @@
+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")
 
-      if !@metadata.attributes.empty?
+      if (!@metadata.attributes.empty? rescue false)
         @attributes = @metadata.attributes.map do |attr, options|
           name = "node['#{attr.gsub("/", "']['")}']"
           [name, options['description'], options['default'], options['choice']]
@@ -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)
@@ -96,6 +108,16 @@ module KnifeCookbookDoc
       end
     end
 
+    def chef_versions
+      if @metadata.methods.include?(:chef_version)
+        @metadata.chef_versions.map do |chef_version, version|
+          format_constraint(chef_version, version)
+        end
+      else
+        []
+      end
+    end
+
     def dependencies
       @metadata.dependencies.map do |cookbook, version|
         format_constraint(cookbook, version)
@@ -162,7 +184,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

@@ -52,14 +52,18 @@ module KnifeCookbookDoc
 
     def attribute_has_default_value?(attribute)
       specification = @native_resource.attribute_specifications[attribute]
-      specification && specification.has_key?(:default)
+      specification && specification.key?(:default)
     end
 
     def attribute_default_value(attribute)
-      if attribute_has_default_value?(attribute)
-        return @native_resource.attribute_specifications[attribute][:default]
+      default = if attribute_has_default_value?(attribute)
+                  @native_resource.attribute_specifications[attribute][:default]
+                end
+
+      if default.is_a?(Chef::DelayedEvaluator)
+        'lazy { ... }'
       else
-        return nil
+        default.inspect
       end
     end
 

data/lib/knife_cookbook_doc/version.rb

@@ -1,3 +1,3 @@
 module KnifeCookbookDoc
-  VERSION = '0.25.0'
+  VERSION = '0.29.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: knife-cookbook-doc
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Mathias Lafeldt
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-07 00:00:00.000000000 Z
+date: 2020-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef
@@ -76,6 +76,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitattributes"
+- ".github/ISSUE_TEMPLATE.md"
 - ".gitignore"
 - ".travis.yml"
 - CHANGELOG.md
@@ -93,6 +94,7 @@ files:
 - fixture/doc/overview.md
 - fixture/gemfile
 - fixture/knife.rb
+- fixture/libraries/default.rb
 - fixture/metadata.rb
 - fixture/recipes/default.rb
 - fixture/resources/default.rb
@@ -103,6 +105,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