yard-chefdoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7c1b1b7c7d48d1fdfe371a9bc0e3208157ea869e
+  data.tar.gz: 48ae1a4b57dd8655ac6924dfab4583bb2bf413b6
+SHA512:
+  metadata.gz: c9ae7cb39a84734379f979d5adda5a25567b319b5de254f986aba5b4b5e1eae6366c455a69129634dcff5e615c71b42176da96c8ec023f82039cc49b4e666126
+  data.tar.gz: f445225e242f27dbe83dd4d5b0ab9a106190d2a5938e3314fdef0fb6541935ef215bde5104a88d6d761eb058adda8ccb5422427b7197913c35eeedaa3d8a5132

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'yard'
+
+group :test do
+  gem 'capybara'
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec-html-matchers'
+  gem 'rspec-rails'
+  gem 'rubocop'
+  gem 'rubygems-tasks'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 RightScale, Inc.
+Copyright (c) 2017 Jörg Herzinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# YARD-Chef
+
+Disclaimer: This YARD plugin is still in the early development stages. Please use with care and expect things to break.
+
+## Description
+
+yard-chefdoc is a [YARD](http://yardoc.org/) plugin for that adds support for documenting [Chef](http://www.chef.io/) cookbooks.
+
+## Installation
+
+This project is still in early development, so it has not yet been released on rubygems.org.
+
+## How to document your Cookbooks
+
+The cookbook to be documented has to be vendored, which can be done using Berkshelfs `vendor` command or by downloading the released cookbook from a Chef Supermarket or Chef Server.
+
+For yard-chefdoc the most important part about the vendor process is that your metadata.rb gets evaluated to a static metadata.json.
+
+### Cookbook README
+
+The cookbook README.md in markdown format will be the landing page. Additionally a list of all all other objects with their short description will be added.
+
+### Cookbook Metadata
+
+Metadata information will be included in the documentation automatically. This requires a `metadata.json` to be present, not a `metadata.rb`. Check "cookbook vendoring" for more info.
+
+### Libraries and standard YARD functionality
+
+Your libraries will be documented out of the box by YARD. See the [YARD Documentation](http://yardoc.org/) on how to document them.
+
+### File headers and descriptions
+
+With Chefs special cookbook directory structure is makes sense to add descriptions for certain files rather than for Classes, Modules etc. like Ruby. For recipe and attribute files yard-chefdoc will try to find a header which is defined by a comment block starting at the first line and ending at the first blank line.
+
+Within this header a description can be given. This is defined to start by a comment line containing the single word `Description` and ending at the end of the comment block/header. A working example is:
+
+```
+#
+# Cookbook Name:: my-cookbook
+# Attribute:: default
+#
+# Copyright (c) 2016 The Authors, All Rights Reserved.
+#
+# Description
+# Here are some default attributes
+
+default['my-cookbook']['brokkoli'] = %(delicious healthy)
+```
+
+In this example the description for the file `attributes/default.rb` would be `Here are some default attributes`. This description can of course also span multiple lines. Mind the blank line after the header, without this the header would serve as a description for the attribute `['my-cookbook']['brokkoli']`.
+
+### Attributes
+
+Attributes are automatically parsed and added to the documentation. Each attribute can have its own description which is simply the comment block above the attribute. Example:
+
+```
+# Set this attribute to define which plugins should be installed
+default['my-application']['plugins'] = %w(github slack ldap)
+```
+
+### Resources
+
+Modern Chef custom resources are automatically documented. Comments on properties and actions are added accordingly.
+
+## Generating Cookbook Docs
+
+To generate documentation you can either use the command line or create a rake task.
+
+Command line:
+```
+cd /path/to/cookbook
+yardoc --plugin chefdoc "**/*.{rb,json}"
+```
+
+Rake task:
+```
+require 'yard'
+
+YARD::Config.load_plugin 'chefdoc'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['<path_to_cookbooks_repo>/**/*.{rb,json}']
+  # t.options = ['--debug']
+end
+```
+
+Then just run `rake yard`.
+
+## Viewing Cookbook Docs
+
+YARD output will be present in a directory named `doc` which will be located in the same folder from where the command was run. The will also be a cache directory with all the information necessary to render the documentation pages in a directory name `.yardoc`.
+
+It is recommended to view these pages from a running YARD server.  To start a local YARD server you should be in the same directory that contains your generated `.yardoc` directory.  Once there run:
+
+`yard server --plugin chefdoc --cache`
+
+For more information about YARD server see [YARD documentation](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#yard_Executable)
+
+# License and Thanks
+
+This project was originally a fork of yard-chef by RightScale, Inc. Special thanks goes to them for providing the base for this.
+
+Copyright (c) 2017 Jörg Herzinger. This code is distributed under the MIT license, see LICENSE for details.<br>
+Copyright (c) 2012 RightScale, Inc.

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/setup'
+require 'rubygems/tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+desc 'Create test docs'
+task :doc_fixtures do
+  FileList.new('test/fixtures/*').each do |cb|
+    FileUtils.cd(cb) do
+      sh 'rm -rf .yardoc doc'
+      sh 'bundle exec yardoc --safe --plugin chefdoc --debug "**/*.{rb,json}"'
+      sh 'bundle exec yard server --plugin chefdoc --debug'
+    end
+  end
+end
+
+Gem::Tasks.new
+
+RSpec::Core::RakeTask.new(:spec, %i[tag trigger] => ['gen_yardoc'])
+
+desc 'Generate yard documentation of all test cookbook'
+task :gen_yardoc do
+  FileList.new('test/fixtures/*').each do |cb|
+    FileUtils.cd(cb) do
+      sh 'bundle exec yardoc --debug --plugin chefdoc "**/*.{rb,json}"'
+    end
+  end
+end

data/lib/yard/cli/stats.rb

@@ -0,0 +1,142 @@
+require 'json'
+
+module YARD
+  module CLI
+    class Stats < Yardoc
+      STATS_ORDER = %i[files modules classes constants attributes methods
+                       chef_attribute_files chef_attributes chef_recipes chef_resources
+                       chef_resource_properties chef_resource_actions]
+
+      def stats_for_chef_recipes
+        objs = all_objects.select { |m| m.type == :recipe }
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.blank? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Recipes', objs.size, undoc.size
+      end
+
+      def stats_for_chef_attribute_files
+        objs = all_objects.select { |m| m.type == :attribute }
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.empty? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Attribute files', objs.size, undoc.size
+      end
+
+      def stats_for_chef_attributes
+        objs = all_objects.select { |m| m.type == :attribute }
+        objs.map!(&:attributes).flatten!
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.empty? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Attributes', objs.size, undoc.size
+      end
+
+      def stats_for_chef_resources
+        objs = all_objects.select { |m| m.type == :resource }
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.blank? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Resources', objs.size, undoc.size
+      end
+
+      def stats_for_chef_resource_properties
+        objs = all_objects.select { |m| m.type == :resource }
+        objs.map!(&:properties).flatten!
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.empty? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Resource properties', objs.size, undoc.size
+      end
+
+      def stats_for_chef_resource_actions
+        objs = all_objects.select { |m| m.type == :resource }
+        objs.map!(&:actions).flatten!
+        undoc = objs.select { |m| !m.docstring.nil? && m.docstring.empty? }
+        @undoc_list |= undoc if @undoc_list
+        output 'Chef Resource actions', objs.size, undoc.size
+      end
+
+      # We don't need the file stats, so remove it
+      remove_method :stats_for_files
+
+      # Overrides the output from Yard itself for better indentation
+      # Prints a statistic to standard out. This method is optimized for
+      # getting Integer values, though it allows any data to be printed.
+      #
+      # @param [String] name the statistic name
+      # @param [Integer, String] data the numeric (or any) data representing
+      #   the statistic. If +data+ is an Integer, it should represent the
+      #   total objects of a type.
+      # @param [Integer, nil] undoc number of undocumented objects for the type
+      # @return [void]
+      def output(name, data, undoc = nil)
+        @total += data if data.is_a?(Integer) && undoc
+        @undocumented += undoc if undoc.is_a?(Integer)
+        data = if undoc
+                 "#{format('%5s', data)} (#{format('%5d', undoc)} undocumented)"
+               else
+                 format('%5s', data)
+               end
+        log.puts("#{format('%-25s', name + ':')} #{format('%s', data)}")
+      end
+
+      # Returns statistics for machine readable output generation
+      #
+      # @param [String] name the statistic name
+      # @param [Integer, String] data the numeric (or any) data representing
+      #   the statistic. If +data+ is an Integer, it should represent the
+      #   total objects of a type.
+      # @param [Integer, nil] undoc number of undocumented objects for the type
+      # @return [Hash] Number of documented and undocumented items
+      def output_hash(name, data, undoc = nil)
+        @total += data if data.is_a?(Integer) && undoc
+        @undocumented += undoc if undoc.is_a?(Integer)
+        percent = data.to_i.zero? ? '100' : ((data.to_i - undoc.to_i) / data.to_f) * 100
+        { name.tr(' ', '_').downcase => { 'name' => name,
+                                          'items' => data.to_i,
+                                          'undocumented' => undoc.to_i,
+                                          'percentage' => percent } }
+      end
+
+      # Prints statistics for different object types in JSON format
+      #
+      # To add statistics for a specific type, add a method +#stats_for_TYPE+
+      # to this class that calls {#output}.
+      def print_statistics_json
+        log.puts JSON.pretty_generate(statistics_hash)
+      end
+
+      def statistics_hash
+        # Use JSON output for the following stats_for_* calls
+        alias output output_hash
+        # This is necessary so we get full access to the stats from the templates. Probably a
+        # bad patch, but for now this is ok.
+        # TODO: Refactor
+        options.verifier = YARD::Verifier.new('[:public].include?(object.visibility)')
+
+        collection = {}
+        @total = 0
+        @undocumented = 0
+        meths = methods.map(&:to_s).grep(/^stats_for_/)
+
+        meths.each { |m| collection.merge!(send(m)) }
+
+        collection['total_percentage'] = total_percentage
+
+        collection
+      end
+
+      # Always use JSON output by default
+      # alias output output_hash
+      # alias print_statistics print_statistics_json
+
+      private
+
+      def total_percentage
+        if @undocumented.zero?
+          100
+        elsif @total.zero?
+          0
+        else
+          (@total - @undocumented).to_f / @total.to_f * 100
+        end
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/code_objects/attribute.rb

@@ -0,0 +1,43 @@
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    class AttributeObject < ChefObject
+      register_element :attribute
+      attr_accessor :attributes
+
+      # Creates a new instance of the AttributeObject which represents a file in
+      # the attributes directory.
+      #
+      # @param namespace [NamespaceObject] namespace to which the attribute belongs
+      # @param name [String] name of the attribute file
+      #
+      # @return [AttributeObject] the newly created AttribteObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @attributes = []
+      end
+
+      # Add a single attribute as an Attribute object (see below)
+      #
+      # @param h [Hash] The attribute hash to add
+      #
+      def add(h)
+        @attributes.push(Attribute.new(h))
+      end
+    end
+
+    # Simple class to handle Attributes and their specifics
+    class Attribute
+      attr_accessor :default, # The default value
+                    :path, # The attributes Hash path. Something like ['cookbook']['one']['two']
+                    :docstring, # The attrbitues docstring
+                    :precedence # The precedence the attribute is set with
+
+      def initialize(h)
+        h.each { |k, v| instance_variable_set("@#{k}", v) }
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/code_objects/chef.rb

@@ -0,0 +1,116 @@
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # The chef object will be the root of your namespace
+    class ChefObject < YARD::CodeObjects::NamespaceObject
+      attr_accessor :file # The file the object appears in
+      attr_accessor :header # The header found in the source file
+
+      # Creates a new ChefObject object.
+      #
+      # @param namespace [NamespaceObject] namespace to which the object belongs
+      # @param name [String] name of the ChefObject
+      #
+      # @return [ChefObject] the newly created ChefObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+
+      # Register a chef element class.
+      #
+      # @param element [Class] chef element class
+      #
+      def self.register_element(element)
+        @@chef_elements ||= {}
+        @@chef_elements[element] = self
+      end
+
+      # Factory for creating and registering chef element object in
+      # YARD::Registry.
+      #
+      # @param namespace [NamespaceObject] namespace to which the object must
+      # belong
+      # @param name [String] name of the chef element
+      # @param type [Symbol, String] type of the chef element
+      #
+      # @return [<type>Object] the element object
+      #
+      def self.register(name, type, file)
+        element = @@chef_elements[type]
+        raise "Invalid chef element type #{type}" unless element
+        element_obj = YARD::Registry.resolve(:root, "#{type}::#{name}")
+        if element_obj.nil?
+          element_obj = element.new(:root, "#{type}::#{name}")
+          log.info "Created [#{type.to_s.capitalize}] #{element_obj.name} => #{element_obj.namespace}"
+          element_obj.chef_init(file)
+        end
+        element_obj
+      end
+
+      # Returns children of an object of a particular type.
+      #
+      # @param type [Symbol] type of ChefObject to be selected
+      #
+      # @return [Array<ChefObject>] list of ChefObjects
+      #
+      def children_by_type(type)
+        children = YARD::Registry.all(type)
+        children.select { |child| child.parent == self }
+      end
+
+      # Does chef specific initalization tasks
+      #
+      # @param file [String] The file of the object thas is being initialized
+      #
+      # @return [ChefObject] The (chef) initialized object
+      #
+      def chef_init(file)
+        self.file = file
+        self.source = IO.read(File.expand_path(file))
+        self.header = find_header_in(source)
+        self.docstring = find_description_in(header)
+      end
+
+      # Gets the file header if available
+      # The header is defined by a every comment line starting at the beginning of the file
+      # Until the first blank line. If no blank line is found then the comment is considered
+      # the following resource's/blocks docstring.
+      #
+      # @return [String] The header of the file. Empty if no header is found
+      #
+      def find_header_in(src)
+        h = []
+        src.each_line do |line|
+          comment = line[/^\s*#\s?(.*)$/, 1]
+          break if comment.nil?
+
+          h.push comment
+        end
+
+        h.join("\n")
+      end
+
+      # Gets the description from the file header.
+      # Currently the docstring of recipes, attributes etc. is looked up in the file
+      # header and starts with a single line containing the keyword "Description".
+      #
+      # @return [String] The description
+      #
+      def find_description_in(header)
+        desc_found = false
+        docstring = []
+        header.each_line do |line|
+          if desc_found
+            docstring.push line
+          elsif line.chomp == 'Description'
+            desc_found = true
+          end
+        end
+
+        docstring.join("\n")
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/code_objects/cookbook.rb

@@ -0,0 +1,55 @@
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    # A CookbookObject represents a Chef cookbook.
+    # See http://wiki.opscode.com/display/chef/Cookbooks for more information
+    # about cookbooks.
+    #
+    class CookbookObject < ChefObject
+      register_element :cookbook
+
+      attr_accessor :docstring_type
+
+      # Cookbook metadata
+      attr_accessor :dependencies
+      attr_accessor :version
+      attr_accessor :source_url
+      attr_accessor :issues_url
+      attr_accessor :maintainer
+      attr_accessor :maintainer_email
+      attr_accessor :license
+      attr_accessor :platforms
+      attr_accessor :gems
+
+      # Creates a new CookbookObject instance.
+      # @param namespace [NamespaceObject] namespace to which the cookbook
+      # belongs
+      # @param name [String] name of the cookbook
+      #
+      # @return [CookbookObject] the newly created CookbookObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @docstring_type = :markdown
+      end
+
+      # Libraries defined in the cookbook.
+      # Catches all classes, modules and defintion directly defined without a namespace
+      #
+      # @return [Array] libraries in the cookbook
+      #
+      def libraries
+        modules = YARD::Registry.all(:module)
+        classes = YARD::Registry.all(:class)
+        root_definitions = YARD::Registry.all(:method).select { |m| m.path =~ /^root#/ }
+
+        classes + modules + root_definitions
+      end
+
+      def metadata
+        [@version, @maintainer, @dependencies]
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/code_objects/recipe.rb

@@ -0,0 +1,29 @@
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    class RecipeObject < ChefObject
+      register_element :recipe
+
+      # Creates a new instance of RecipeObject.
+      #
+      # @param namespace [NamespaceObject] namespace to which the recipe belongs
+      # @param name [String] name of the recipe
+      #
+      # @return [RecipeObject] the newly created RecipeObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+      end
+
+      # Needed by the template to render recipe source code.
+      # Since we always display the full source we start with 1
+      #
+      # @return [Integer] 1
+      #
+      def line
+        1
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/code_objects/resource.rb

@@ -0,0 +1,70 @@
+require 'yard'
+
+module YARD::CodeObjects
+  module Chef
+    class ResourceObject < ChefObject
+      register_element :resource
+      attr_accessor :properties,
+                    :actions,
+                    :default_action,
+                    :resource_name,
+                    :load_current_value
+
+      # Creates a new instance of the ResourceObject
+      #
+      # @param namespace [NamespaceObject] namespace to which the resource belongs
+      # @param name [String] name of the resource. This is the base name which chef
+      #                      automatically generates.
+      #
+      # @return [ResourceObject] the newly created ResourceObject
+      #
+      def initialize(namespace, name)
+        super(namespace, name)
+        @resource_name = name
+        @properties = []
+        @actions = []
+      end
+
+      # Add a single property as an Property object (see below)
+      #
+      # @param h [Hash] The property hash to add
+      #
+      def add_property(h)
+        @properties.push(Property.new(h))
+      end
+
+      # Add an action as an Action object (see below)
+      #
+      # @param h [Hash] The action hash to add
+      #
+      def add_action(h)
+        @actions.push(Action.new(h))
+      end
+    end
+
+    # Simple class to handle Properties and their specifics
+    # Full docs here http://www.rubydoc.info/gems/chef/Chef%2FMixin%2FProperties%2FClassMethods:property
+    class Property
+      attr_accessor :identifier, # The name of the property
+                    :docstring, # The attrbitues docstring
+                    :type, # The ruby type of the property
+                    :options # The various property options
+
+      def initialize(h)
+        h.each { |k, v| instance_variable_set("@#{k}", v) }
+      end
+    end
+
+    # Simple class to handle actions
+    class Action
+      attr_accessor :identifier, # The name of the action
+                    :source,     # The source of the action block
+                    :docstring,  # The actions docstring
+                    :line        # The line number of the first line of the block needed for the output formatting
+
+      def initialize(h)
+        h.each { |k, v| instance_variable_set("@#{k}", v) }
+      end
+    end
+  end
+end

data/lib/yard-chefdoc/handlers/attribute.rb

@@ -0,0 +1,32 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles attributes in cookbook
+    class AttributeHandler < Base
+      MATCH = /^\s*(node\.)?(default|force_default|normal|override|force_override)(\[.+?\])\s*=\s*(.+)/m
+      in_file(%r{^attributes\/.*\.rb$})
+      handles MATCH
+
+      def process
+        attrib_obj = ChefObject.register(filename, :attribute, statement.file)
+
+        docstring_is_header = (statement.docstring == attrib_obj.header)
+        attrib_obj.add attr_hash(docstring_is_header) if statement.type == :assign
+      end
+
+      # Creates the hash to initialize the single attribute object
+      #
+      # @return [Hash] the hash to initialize the attribute in the attribute code object
+      #
+      def attr_hash(nodoc)
+        {
+          precedence: statement.jump(:ident).source,
+          default: statement.jump(:assign)[1].source,
+          docstring: nodoc ? '' : statement.docstring,
+          path: statement.source.match(MATCH)[3]
+        }
+      end
+    end
+  end
+end