yard-chefdoc 0.1.0

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

@@ -0,0 +1,36 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Base handler for chef elements.
+    class Base < YARD::Handlers::Ruby::Base
+      include YARD::CodeObjects::Chef
+
+      # Gets the name of the handled object.
+      #
+      def name
+        statement.parameters.first.jump(:string_content, :ident).source
+      end
+
+      # Gets the filename which is often used as the object name in chef
+      #
+      # @return [String] the file name without the rb extension
+      #
+      def filename
+        File.basename(statement.file, '.rb')
+      end
+
+      # Registers the cookbook in {YARD::Registry} and returns the same.
+      #
+      # @return [ChefObject] the ChefObject
+      #
+      def cookbook
+        cbs = YARD::Registry.all(:cookbook)
+        raise 'Something went wrong! Found more that one cookbook.' if cbs.length > 1
+        raise 'Something went wrong! Could not find any cookbook' if cbs.empty?
+
+        cbs.first
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles specific cookbook information like README, description and version.
+    #
+    class CookbookHandler < Base
+      in_file(/^metadata\.json$/)
+      handles(/.*/) # Handle the file itself, so everything in it
+
+      def process
+        metadata = JSON.parse(File.read(File.expand_path(statement.file)))
+        base_dir = File.dirname(statement.file)
+
+        cookbook_obj = cookbook
+
+        %w[name version dependencies source_url
+           issues_url maintainer maintainer_email
+           license platforms gems].each do |m|
+          cookbook_obj.send("#{m}=", metadata[m]) if metadata.key?(m)
+        end
+
+        cookbook_obj.docstring = docstring(base_dir)
+        cookbook_obj.docstring_type = :markdown
+      end
+
+      # Generates docstring from the README file.
+      #
+      # @return [YARD::Docstring] the docstring
+      #
+      def docstring(base_dir)
+        string = ''
+        readme_path = base_dir + '/README.md'
+        string = IO.read(readme_path) if File.exist?(readme_path)
+
+        YARD::DocstringParser.new.parse(string).to_docstring
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles "recipes" in a cookbook.
+    class RecipeHandler < Base
+      in_file(%r{^recipes\/.*\.rb$})
+      handles(/.*/) # Handle the file itself, so everything in it
+
+      def process
+        ChefObject.register(filename, :recipe, statement.file)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles actions in custom resources and LWRPs
+    class ResourceActionHandler < Base
+      in_file(%r{^resources\/.*\.rb$})
+      handles method_call(:action)
+
+      def process
+        resource_obj = ChefObject.register(filename, :resource, statement.file)
+
+        docstring_is_header = (statement.docstring == resource_obj.header)
+        resource_obj.add_action action_hash(docstring_is_header)
+      end
+
+      # Creates the hash to initialize the single resource property object
+      #
+      # @return [Hash] the hash to initialize the property in the resource code object
+      #
+      def action_hash(nodoc)
+        {
+          identifier: statement[1][0].source.to_s[1..-1],
+          source: statement.source,
+          docstring: nodoc ? '' : statement.docstring,
+          line: statement.line
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles the default_action in custom resources and LWRPs
+    class ResourceDefaultActionHandler < Base
+      in_file(%r{^resources\/.*\.rb$})
+      handles method_call(:default_action)
+
+      def process
+        resource_obj = ChefObject.register(filename, :resource, statement.file)
+        resource_obj.default_action = statement.parameters[0][0][0].source # Gets the first parameter as string
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles properties in custom resources and LWRPs
+    class ResourcePropertyHandler < Base
+      in_file(%r{^resources\/.*\.rb$})
+      handles method_call(:property)
+
+      def process
+        resource_obj = ChefObject.register(filename, :resource, statement.file)
+
+        docstring_is_header = (statement.docstring == resource_obj.header)
+        resource_obj.add_property res_prop_hash(docstring_is_header)
+      end
+
+      # Creates the hash to initialize the single resource property object
+      #
+      # @return [Hash] the hash to initialize the property in the resource code object
+      #
+      def res_prop_hash(nodoc)
+        props = {}
+        statement[1].entries.each do |e|
+          next if e == false
+          if %i[var_ref array].include?(e.type)
+            props[:type] = e.source
+          elsif e.type == :symbol_literal
+            props[:identifier] = e.source.delete(':')
+          elsif e.type == :list
+            props[:options] = parse_option_list(e)
+          end
+        end
+        props[:docstring] = nodoc ? '' : statement.docstring
+
+        props
+      end
+
+      # Goes through the option list AST node and returns a simple hash
+      #
+      # @return [Hash] The options passed as a hash
+      #
+      def parse_option_list(list)
+        return nil if list.nil? || list.empty?
+        opts = {}
+        list.each do |opt|
+          next unless opt.type == :assoc
+          opts[opt[0].source.delete(':')] = opt[1].source
+        end
+
+        opts
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+require 'yard'
+
+module YARD::Handlers
+  module Chef
+    # Handles the resource name in custom resources and LWRPs
+    class ResourceResourceNameHandler < Base
+      in_file(%r{^resources\/.*\.rb$})
+      handles method_call(:resource_name)
+
+      def process
+        resource_obj = ChefObject.register(filename, :resource, statement.file)
+        resource_obj.resource_name = statement.parameters[0][0][0].source # Gets the first parameter as string
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module YARD::Templates::Helpers
+  # The chef helper module
+  module ChefHelper
+    # Returns children of an object of a particular type sorted the chef
+    # way. This means that the object with the name 'default' will be first
+    # and any remaining objects will be sorted alphabetically.
+    #
+    # @param type [Symbol] type of CookbookObject to be selected
+    #
+    # @return [Array<CookbookObject>] list of CookbookObjects
+    #
+    def chefsorted_objects(type = nil)
+      children = ::YARD::Registry.all.select { |o| o.type == type }.sort { |x, y| x.name.to_s <=> y.name.to_s }
+      default_index = children.find_index { |r| r.name.to_s == 'default' }
+
+      return children if default_index.nil?
+
+      default_child = children.delete_at(default_index)
+      [default_child].concat(children)
+    end
+  end
+end

data/lib/yard-chefdoc/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module YARD
+  module CodeObjects
+    module Chef
+      VERSION = '0.1.0'.freeze
+    end
+  end
+end

data/lib/yard-chefdoc.rb

@@ -0,0 +1,50 @@
+require 'yard'
+require 'json'
+
+require_relative 'yard/cli/stats'
+
+require 'yard-chefdoc/code_objects/chef'
+require 'yard-chefdoc/code_objects/cookbook'
+require 'yard-chefdoc/code_objects/recipe'
+require 'yard-chefdoc/code_objects/attribute'
+require 'yard-chefdoc/code_objects/resource'
+
+require 'yard-chefdoc/handlers/base'
+require 'yard-chefdoc/handlers/cookbook'
+require 'yard-chefdoc/handlers/recipe'
+require 'yard-chefdoc/handlers/attribute'
+require 'yard-chefdoc/handlers/resource_property'
+require 'yard-chefdoc/handlers/resource_action'
+require 'yard-chefdoc/handlers/resource_resource_name'
+require 'yard-chefdoc/handlers/resource_default_action'
+
+require 'yard-chefdoc/template_helpers/chef'
+
+require 'yard-chefdoc/version'
+
+module YARD::CodeObjects
+  module Chef
+    # Initialize the whole magic
+    namespace = ChefObject.new(nil, :root)
+    CookbookObject.new(namespace, :root)
+  end
+
+  # YARD::Tags::Library.define_tag('Recipe description', :recipe)
+
+  # Register template directory for the chef plugin
+  template_dir = File.expand_path('../templates', File.dirname(__FILE__))
+  YARD::Templates::Engine.register_template_path(template_dir.to_s)
+end
+
+module YARD
+  module CLI
+    class Yardoc
+      # This overrides the method from Yard adding Chefs own objects to be rendered
+      # as individual pages. This adds recipes, attributes...
+      # @return [Array<CodeObjects::Base>] a list of code objects to process
+      def all_objects
+        Registry.all(:root, :module, :class, :recipe, :attribute, :resource)
+      end
+    end
+  end
+end

data/spec/attributes_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe 'home page' do
+  before(:each) do
+    visit('/docs/attribute/default')
+  end
+
+  it 'shows the description' do
+    expect(page).to have_content('Some default attributes')
+  end
+
+  it 'has the test-attribute1' do
+    expect(page).to have_content("['test-cookbook1']['test-attribute1']")
+  end
+
+  it 'has the test-attribute1 description' do
+    expect(page).to have_content('This is the documentation of an attribute')
+  end
+end

data/spec/home_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe 'home page' do
+  before(:each) do
+    visit('/')
+  end
+
+  it 'presents the README' do
+    expect(page).to have_content('Lorem ipsum dolor sit amet')
+  end
+
+  it 'shows metadata version' do
+    expect(page).to have_tag('td', text: '0.1.0')
+  end
+
+  it 'does not show empty license' do
+    expect(page).to_not have_tag('td', text: 'License')
+  end
+
+  it 'shows the recipe summary' do
+    expect(page).to have_content('Recipes summary')
+    expect(page).to have_content('Installs the system package for some_service')
+  end
+
+  it 'shows the attribute summary' do
+    expect(page).to have_content('Attributes summary')
+  end
+
+  it 'gives an overview of the libraries' do
+    expect(page).to have_content('Finder')
+    expect(page).to have_content('Finder::Node')
+    expect(page).to have_content('MyTestLib')
+  end
+
+  it 'shows cookbook documentation table' do
+    expect(page).to have_content('Cookbook documentation statistics')
+  end
+
+  it 'shows overall percentage' do
+    expect(page).to have_content('Total percentage 86.96%')
+  end
+end

data/spec/recipes_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe 'home page' do
+  before(:each) do
+    visit('/docs/recipe/default')
+  end
+
+  it 'shows the description' do
+    expect(page).to have_content('This is the description for the default recipe')
+  end
+
+  it 'shows the recipe file name and location' do
+    expect(find(:xpath, "//span[@class='info file']").text).to eq('# File \'recipes/default.rb\'')
+  end
+end

data/spec/resources_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe 'home page' do
+  before(:each) do
+    visit('/docs/resource/etc_dir')
+  end
+
+  it 'shows the default_action as create' do
+    expect(page).to have_content('Default action: create')
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,32 @@
+require 'rspec'
+require 'rspec-html-matchers'
+require 'action_view'
+
+# Add this to load Capybara integration:
+require 'capybara'
+require 'capybara/rspec'
+# require 'capybara/rails'
+require 'capybara/dsl'
+
+require 'yard'
+require_relative '../lib/yard-chefdoc'
+
+RSpec.configure do |config|
+  config.include Capybara::DSL
+  config.include RSpecHtmlMatchers
+end
+
+# disable :run
+# From: https://github.com/lsegal/yard/blob/master/lib/yard/cli/server.rb#L50
+doc_root = File.expand_path('../../test/fixtures/test-cookbook1', __FILE__)
+server_options = {
+  Port: 8808
+}
+db = File.expand_path('.yardoc', doc_root)
+libver = YARD::Server::LibraryVersion.new('test-cookbook1', nil, db)
+libver.source_path = doc_root
+libraries = {
+  'test-cookbook1' => [libver]
+}
+options = SymbolHash.new(false).update(single_library: true, caching: false)
+Capybara.app = YARD::Server::RackAdapter.new(libraries, options, server_options)

data/templates/default/attribute/html/attribute.erb

@@ -0,0 +1,30 @@
+<h2>Attribute <%= object.name %></h2>
+  <%= htmlify(object.docstring, :markdown) %>
+  <table style="width:100%">
+    <thead>
+      <th>Attribute</th>
+      <th>Precedence</th>
+      <th>Description</th>
+      <th>Default value</th>
+    </thead>
+    <tbody>
+      <% n = 2 %>
+      <% object.attributes.each do |attribute| %>
+        <tr class="r<%= n %>">
+          <td>
+            <strong><%= attribute.path %></strong>
+          </td>
+          <td><%= attribute.precedence %></td>
+          <td><%= htmlify attribute.docstring %></td>
+          <td>
+            <% if attribute.default.size > 60 %>
+            <span>[<a href="#" onclick="return false;" class="toggleSource">View source</a>]</span><br /><span class="source_code"><%= htmlify attribute.default %></span>
+            <% else %>
+            <%= htmlify attribute.default %>
+            <%end%>
+          </td>
+        </tr>
+        <% n = n == 1 ? 2 : 1 %>
+      <% end %>
+    </tbody>
+  </table>

data/templates/default/attribute/html/setup.rb

@@ -0,0 +1,5 @@
+include Helpers::ChefHelper
+
+def init
+  sections.push :attribute
+end

data/templates/default/cookbook/html/attributes.erb

@@ -0,0 +1,14 @@
+<% attributes = chefsorted_objects(:attribute) %>
+<% if attributes.size > 0 %>
+  <h2>Attributes summary</h2>
+  <ul class="summary">
+    <% attributes.each do |attribute| %>
+      <li>
+        <span class="summary_signature">
+          <strong><a href="<%= url_for(attribute,nil) %>"><%= attribute.name %></a></strong>
+        </span>
+        <span class="summary_desc"><%= htmlify(attribute.docstring, :markdown) %></span>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/templates/default/cookbook/html/cookbook_title.erb

@@ -0,0 +1,2 @@
+<h1>Cookbook <%= object.name.to_s %></h1>
+<%= yieldall %>

data/templates/default/cookbook/html/docstring.erb

@@ -0,0 +1 @@
+<%= htmlify(object.docstring, object.docstring_type) %>

data/templates/default/cookbook/html/element_details.erb

@@ -0,0 +1,3 @@
+<div class="method_details_list">
+  <%= yieldall %>
+</div>

data/templates/default/cookbook/html/generated_docs.erb

@@ -0,0 +1,2 @@
+<h1>Cookbook elements overview</h1>
+<%= yieldall %>

data/templates/default/cookbook/html/libraries.erb

@@ -0,0 +1,13 @@
+<% libraries = object.libraries %>
+<% if libraries.size > 0 %>
+  <h2>Libraries</h2>
+  <ul class="summary compact">
+    <% libraries.each do |lib| %>
+      <li>
+        <span class="summary_signature">
+          <a href="<%= url_for(lib, nil) %>"><%= lib %></a>
+        </span>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/templates/default/cookbook/html/metadata.erb

@@ -0,0 +1,86 @@
+<table class="metadata-box">
+  <tr>
+    <th class="merged" colspan="2">Cookbook metadata</th>
+  </tr>
+  <% { 'name' => 'Name',
+       'version' => 'Version',
+       'maintainer' => 'Maintainer',
+       'maintainer_email' => 'Contact',
+       'license' => 'License',
+       'source_url' => 'Source',
+       'issues_url' => 'Issues'}.each do |m, n| %>
+  <% meta_info = object.send(m.to_sym) %>
+  <% next if meta_info.nil? || meta_info.empty? %>
+  <tr>
+    <td><%= n %></td>
+    <% if m.end_with?('_url') %>
+    <td><a href="<%= meta_info %>" target="_blank"><%= meta_info %></a></td>
+    <% else %>
+    <td><%= meta_info %></td>
+    <% end %>
+  </tr>
+  <% end %>
+
+  <% unless object.dependencies.nil? || object.dependencies.empty? %>
+  <tr class="section">
+    <td class="merged" colspan="2">Dependencies</td>
+  </tr>
+  <% object.dependencies.each do |cookbook, version| %>
+  <tr>
+    <td><%= cookbook %></td>
+    <td><%= version %> </td>
+  </tr>
+  <% end %>
+  <% end %>
+  <% unless object.platforms.nil? || object.platforms.empty? %>
+  <tr class="section">
+    <td class="merged" colspan="2">Supported platforms</td>
+  </tr>
+  <% object.platforms.each do |platform, version| %>
+  <tr>
+    <td><%= platform %></td>
+    <td><%= version %> </td>
+  </tr>
+  <% end %>
+  <% end %>
+  <% unless object.gems.nil? || object.gems.empty? %>
+  <tr class="section">
+    <td class="merged" colspan="2">Rubygem dependencies</td>
+  </tr>
+  <% object.gems.each do |g| %>
+  <tr>
+    <td colspan="2"><%= g %></td>
+  </tr>
+  <% end %>
+  <% end %>
+</table>
+
+<table class="metadata-box">
+  <tr>
+    <th class="merged" colspan="2">Cookbook documentation statistics</th>
+  </tr>
+  <tr>
+    <td>Total percentage</td>
+    <td><%= @cookbook_statistics['total_percentage'].round(2) %>%</td>
+  </tr>
+  <tr>
+    <td class="merged" colspan="2">Chef</th>
+  </tr>
+  <% @cookbook_statistics.each do |stat, values| %>
+  <% next unless (values.is_a?(Hash) && stat.start_with?('chef_') && !values['items'].zero?) %>
+  <tr>
+    <td><%= values['name'].sub(/^Chef\s/, '') %></td>
+    <td><%= values['percentage'].to_f.round(1) %>% (<%= values['items'] - values['undocumented'] %> of <%= values['items'] %>)</td>
+  </tr>
+  <% end %>
+  <tr>
+    <td class="merged" colspan="2">Ruby</th>
+  </tr>
+  <% @cookbook_statistics.each do |stat, values| %>
+  <% next unless (values.is_a?(Hash) && !stat.start_with?('chef_') && !values['items'].zero?) %>
+  <tr>
+    <td><%= values['name'] %></td>
+    <td><%= values['percentage'].to_f.round(1) %>% (<%= values['items'] - values['undocumented'] %> of <%= values['items'] %>)</td>
+  </tr>
+  <% end %>
+</table>

data/templates/default/cookbook/html/recipes.erb

@@ -0,0 +1,14 @@
+<% recipes = chefsorted_objects(:recipe) %>
+<% if recipes.size > 0 %>
+  <h2>Recipes summary</h2>
+  <ul class="summary">
+    <% recipes.each do |recipe| %>
+      <li>
+        <span class="summary_signature">
+          <strong><a href="<%= url_for(recipe, nil) %>"><%= recipe.name %></a></strong>
+        </span>
+        <span class="summary_desc"><%= htmlify(recipe.docstring, :markdown) %></span>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/templates/default/cookbook/html/resources.erb

@@ -0,0 +1,14 @@
+<% resources = chefsorted_objects(:resource) %>
+<% if resources.size > 0 %>
+  <h2>Resources summary</h2>
+  <ul class="summary">
+    <% resources.each do |resource| %>
+      <li>
+        <span class="summary_signature">
+          <strong><a href="<%= url_for(resource,nil) %>"><%= resource.name %></a></strong>
+        </span>
+        <span class="summary_desc"><%= htmlify(resource.docstring, :markdown) %></span>
+      </li>
+    <% end %>
+  </ul>
+<% end %>

data/templates/default/cookbook/html/setup.rb

@@ -0,0 +1,9 @@
+include Helpers::ChefHelper
+include T('default/module')
+
+def init
+  @cookbook_statistics = YARD::CLI::Stats.new(false).statistics_hash
+
+  recipe_parts = %I[recipes attributes resources libraries]
+  sections [:cookbook_title, :metadata, :docstring, :generated_docs, recipe_parts]
+end