puppet-strings 0.4.0

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb

@@ -0,0 +1,91 @@
+include T('default/module')
+
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, :box_info,
+    :method_summary, [:item_summary],
+    :method_details_list, [T('method_details')]
+
+  @methods = object.children
+  @template_helper = TemplateHelper.new
+end
+
+def header
+  # The list is expected to only contain one type of function
+  if @methods[0]['puppet_4x_function']
+    @header_text = "Puppet 4 Functions"
+  else
+    @header_text = "Puppet 3 Functions"
+  end
+
+  erb(:header)
+end
+
+def box_info
+  @source_files = []
+
+  @methods.each do |method|
+    # extract the file name and line number for each method
+    file_name = method.files[0][0]
+    line_number = method.files[0][1]
+
+    @source_files.push([method.name, "#{file_name} (#{line_number})"])
+  end
+
+  erb(:box_info)
+end
+
+def method_summary
+  @method_details = []
+  @html_helper = HTMLHelper.new
+
+  @methods.each do |method|
+    # If there are multiple sentences in the method description, only
+    # use the first one for the summary. If the author did not include
+    # any periods in their summary, include the whole thing
+    first_sentence = method.docstring.match(/^(.*?)\./)
+    brief_summary = first_sentence ? first_sentence : method.docstring
+
+    return_tag = method.tags.find { |tag| tag.tag_name == "return"}
+    return_types = return_tag.nil? ? nil : return_tag.types
+
+    @method_details.push({:name => method.name, :short_desc => brief_summary, :return_types => return_types})
+  end
+
+  erb(:method_summary)
+end
+
+def method_details_list
+  @class_details = []
+  @html_helper = HTMLHelper.new
+
+  @methods.each do |object|
+
+    method_info = @template_helper.extract_tag_data(object)
+    param_details = nil
+    param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+
+    if object['puppet_4x_function']
+      # Extract the source code
+      source_code = object.source
+      # Extract the parameters for the source code
+      parameters = source_code.match(/(?:def .*)\((.*?)\)/)
+      # Convert the matched string into an array of strings
+      params = parameters.nil? ? nil :  parameters[1].split(/\s*,\s*/)
+
+      param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil?
+      @template_helper.check_types_match_docs object, param_details
+      @template_helper.check_parameters_match_docs object
+    else
+      param_details = @template_helper.comment_only_param_details(param_tags)
+    end
+
+    method_info[:params] = param_details
+
+    @class_details.push(method_info)
+  end
+
+  erb(:method_details_list)
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb

@@ -0,0 +1,192 @@
+require "puppet"
+
+# A class containing helper methods to aid in the extraction of relevant data
+# from comments and YARD tags
+class TemplateHelper
+  # Extracts data from comments which include the supported YARD tags
+  def extract_tag_data(object)
+    examples = Hash.new
+    example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
+    example_tags.each do |example|
+      examples["#{example.name}"] = example.text
+    end
+
+    return_tag = object.tags.find { |tag| tag.tag_name == "return"}
+    return_text = return_tag.nil? ? nil : return_tag.text
+    return_types = return_tag.nil? ? nil : return_tag.types
+    return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]
+
+    since_tag = object.tags.find { |tag| tag.tag_name == "since"}
+    since_text = since_tag.nil? ? nil : since_tag.text
+
+    {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
+  end
+
+  # Given the parameter information and YARD param tags, extracts the
+  # useful information and returns it as an array of hashes which can
+  # be printed and formatted as HTML
+  #
+  # @param parameters [Array] parameter details obtained programmatically
+  # @param tags_hash [Array] parameter details obtained from comments
+  # @param fq_name [Boolean] does this parameter have a fully qualified name?
+  #
+  # @return [Hash] The relevant information about each parameter with the following keys/values:
+  #   {:name    => [String] The name of the parameter
+  #    :fq_name => [String] The fully qualified parameter name
+  #    :desc    => [String] The description provided in the comment
+  #    :types   => [Array] The parameter type(s) specified in the comment
+  #    :exists  => [Boolean] True only if the parameter exists in the documented logic and not just in a comment}
+  def extract_param_details(parameters, tags_hash, fq_name = false)
+    parameter_info = []
+
+    # Extract the information for parameters that exist
+    # as opposed to parameters that are defined only in the comments
+    parameters.each do |param|
+      if fq_name
+        param_name = param[0]
+        fully_qualified_name = param[1]
+      else
+        param_name = param
+      end
+
+      param_tag = tags_hash.find { |tag| tag.name == param_name }
+
+      description = param_tag.nil? ? nil : param_tag.text
+      param_types = param_tag.nil? ? nil : param_tag.types
+
+      param_details = {:name => param_name, :desc => description, :types => param_types, :exists? => true}
+
+      if fq_name
+        param_details[:fq_name] = fully_qualified_name
+      end
+
+      parameter_info.push(param_details)
+    end
+
+    # Check if there were any comments for parameters that do not exist
+    tags_hash.each do |tag|
+      param_exists = false
+      parameter_info.each do |parameter|
+        if parameter[:name] == tag.name
+          param_exists = true
+        end
+      end
+      if !param_exists
+        parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
+      end
+    end
+
+    parameter_info
+  end
+
+  # Generates parameter information in situations where the information can only
+  # come from YARD tags in the comments, not from the code itself. For now the only
+  # use for this is 3x functions. In this case exists? will always be true since we
+  # cannot verify if the parameter exists in the code itself. We must trust the user
+  # to provide information in the comments that is accurate.
+  #
+  # @param param_tags [Array] parameter details obtained from comments
+  #
+  # @return [Hash] The relevant information about each parameter with the following keys/values:
+  #   {:name          => [String] The name of the parameter
+  #    :desc          => [String] The description provided in the comment
+  #    :types         => [Array] The parameter type(s) specified in the comment
+  #    :exists        => [Boolean] True only if the parameter exists in the documented logic and not just in a comment
+  #    :puppet_3_func => [Boolean] Are these parameters for a puppet 3 function? (relevant in HTML generation)}
+  def comment_only_param_details(param_tags)
+    return if param_tags.empty?
+
+    parameter_info = []
+
+    param_tags.each do |tag|
+      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => true, :puppet_3_func => true})
+    end
+
+    parameter_info
+  end
+
+  # Check that any types specified in the docstrings match the actual method
+  # types. This is used by puppet 4x functions and defined types.
+  # @param object the code object to examine for parameters names
+  def check_types_match_docs(object, params_hash)
+    # We'll need this to extract type info from the type specified by the
+    # docstring.
+    type_parser = Puppet::Pops::Types::TypeParser.new
+    type_calculator = Puppet::Pops::Types::TypeCalculator.new
+
+    object.type_info.each do |function|
+      function.keys.each do |key|
+        if function[key].class == String
+          begin
+            instantiated = type_parser.parse function[key]
+          rescue Puppet::ParseError
+            # Likely the result of a malformed type
+            next
+          end
+        else
+          instantiated = function[key]
+        end
+        params_hash.each do |param|
+          if param[:name] == key and param[:types] != nil
+            param[:types].each do |type|
+              param_instantiated = type_parser.parse type
+              if not type_calculator.assignable? instantiated, param_instantiated
+                actual_types = object.type_info.map do |sig|
+                  sig[key].to_s if sig[key]
+                end.compact
+                # Get the locations where the object can be found. We only care about
+                # the first one.
+                locations = object.files
+                warning = <<-EOS
+[warn]: @param tag types do not match the code. The #{param[:name]}
+    parameter is declared as types #{param[:types]} in the docstring,
+    but the code specifies the types #{actual_types}
+ EOS
+
+                # If the locations aren't in the shape we expect then report that
+                # the file number couldn't be determined.
+                if locations.length >= 1 and locations[0].length == 2
+                  file = locations[0][0]
+                  line = locations[0][1]
+                  warning += "    in the file #{file} near line #{line}."
+                else
+                  warning += "    Sorry, the file and line number could " +
+                             "not be determined."
+                end
+                $stderr.puts warning
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # Check that the actual function parameters match what is stated in the docs.
+  # If there is a mismatch, print a warning to stderr.
+  # This is necessary for puppet classes and defined types. This type of
+  # warning will be issued for ruby code by the ruby docstring parser.
+  # @param object the code object to examine for parameters names
+  def check_parameters_match_docs(object)
+    param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+    names = object.parameters.map {|l| l.first.gsub(/\W/, '') }
+    locations = object.files
+    param_tags.each do |tag|
+      if not names.include?(tag.name)
+        if locations.length >= 1 and locations[0].length == 2
+          file_name = locations[0][0]
+          line_number = locations[0][1]
+          $stderr.puts <<-EOS
+[warn]: The parameter #{tag.name} is documented, but doesn't exist in
+    your code, in file #{file_name} near line #{line_number}.
+EOS
+        else
+          $stderr.puts <<-EOS
+[warn]: The parameter #{tag.name} is documented, but doesn't exist in
+    your code. Sorry, the file and line number could not be determined.
+EOS
+        end
+      end
+    end
+  end
+end

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/docstring.erb

@@ -0,0 +1,34 @@
+<div class="docstring">
+  <div class="discussion">
+    <p><%= htmlify(Puppet::Util::Docs::scrub(@class_details[:desc])) %></p>
+  </div>
+</div>
+<div class="tags">
+  <% if @class_details[:examples] != {}%>
+    <div class="examples">
+    <p class="tag_title">Examples:</p>
+    <% @class_details[:examples].each do |title, text| %>
+      <div class="inline"><p><%= title %></p></div>
+      <pre class="example code"><code><span><%= text %></span></code></pre>
+    <% end %>
+    </div>
+  <% end %>
+  <% if @class_details[:since] %>
+    <p class="tag_title">Since:</p>
+    <ul class="since">
+      <li>
+        <div class="inline">
+          <p><%= @class_details[:since] %></p>
+        </div>
+      </li>
+    </ul>
+  <% end %>
+  <% if @class_details[:return] %>
+    <p class="tag_title">Return:</p>
+    <ul class="return">
+      <li>
+        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
+      </li>
+    </ul>
+  <% end %>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/header.erb

@@ -0,0 +1,5 @@
+<div class='module_header'>
+  <h1>
+    <%= @header_text %>
+  </h1>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/parameter_details.erb

@@ -0,0 +1,12 @@
+<h2>Parameter Summary</h2>
+<div class="tags">
+  <ul class="param">
+    <%= @html_helper.generate_parameters(@param_details, object) %>
+  </ul>
+</div>
+<h2>Features</h2>
+<div class="tags">
+  <ul class="feature">
+    <%= @html_helper.generate_features(@feature_details, object) %>
+  </ul>
+</div>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/provider_details.erb

@@ -0,0 +1,10 @@
+<h2>Available Providers</h2>
+<% if @providers != [] %>
+<div class="tags">
+  <ul class="command">
+    <% @providers.each do |provider| %>
+      <li><a href="<%= provider.name.to_s %>.html"><tt><%= provider.name.to_s %></tt></a></li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

data/lib/puppet_x/puppetlabs/strings/yard/templates/default/type/setup.rb

@@ -0,0 +1,55 @@
+include T('default/module')
+
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, :box_info, :pre_docstring, :docstring, :parameter_details, :provider_details
+
+  @template_helper = TemplateHelper.new
+  @html_helper = HTMLHelper.new
+end
+
+def header
+  @header_text = object.header_name
+
+  erb(:header)
+end
+
+def provider_details
+  type_name = object.name.to_s
+  @providers = YARD::Registry.all(:provider).select { |t| t.type_name == type_name }
+
+  erb(:provider_details)
+end
+
+def parameter_details
+  params = object.parameter_details.map { |h| h[:name] }
+  # Put properties and parameters in one big list where the descriptions are
+  # scrubbed and htmlified and the namevar is the first element, the ensure
+  # property the second, and the rest are alphabetized.
+  @param_details = (object.parameter_details + object.property_details).each {
+    |h| h[:desc] = htmlify(Puppet::Util::Docs::scrub(h[:desc])) if h[:desc]
+  }.sort { |a, b| a[:name] <=> b[:name] }
+  # Float ensurable and namevars to the top of the list
+  @param_details = @param_details.partition{|a| a[:name] == 'ensure'}.flatten
+  @param_details = @param_details.partition{|a| a[:namevar]}.flatten
+
+  @feature_details = object.features
+  @template_helper.check_parameters_match_docs object
+
+  erb(:parameter_details)
+end
+
+def header
+  @header_text = "Puppet Type: #{object.name}"
+
+  erb(:header)
+end
+
+def docstring
+
+  @class_details = @template_helper.extract_tag_data(object)
+
+  erb(:docstring)
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: puppet-strings
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Puppet Labs
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puppet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Puppet documentation via YARD
+email: info@puppetlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/puppet-strings/rake_tasks.rb
+- lib/puppet/application/strings.rb
+- lib/puppet/face/strings.rb
+- lib/puppet/feature/rgen.rb
+- lib/puppet/feature/yard.rb
+- lib/puppet_x/puppetlabs/strings.rb
+- lib/puppet_x/puppetlabs/strings/actions.rb
+- lib/puppet_x/puppetlabs/strings/pops/yard_statement.rb
+- lib/puppet_x/puppetlabs/strings/pops/yard_transformer.rb
+- lib/puppet_x/puppetlabs/strings/util.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/defined_type_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/host_class_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/method_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/provider_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/puppet_namespace_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/code_objects/type_object.rb
+- lib/puppet_x/puppetlabs/strings/yard/core_ext/yard.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/base.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/defined_type_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/heredoc_helper.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/host_class_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/provider_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/puppet_3x_function_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/puppet_4x_function_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/handlers/type_handler.rb
+- lib/puppet_x/puppetlabs/strings/yard/json_registry_store.rb
+- lib/puppet_x/puppetlabs/strings/yard/monkey_patches.rb
+- lib/puppet_x/puppetlabs/strings/yard/parser.rb
+- lib/puppet_x/puppetlabs/strings/yard/tags/directives.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_class.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_manifest.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_plugin.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_provider.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/full_list_puppet_type.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/fulldoc/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/box_info.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/html/subclasses.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/hostclass/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/html_helper.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/layout/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/html/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/text/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/command_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/confine_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/default_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/docstring.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/feature_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/provider/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/box_info.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_details_list.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/docstring.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/header.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/parameter_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/provider_details.erb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/html/setup.rb
+- lib/puppet_x/puppetlabs/strings/yard/templates/default/type/setup.rb
+homepage: https://github.com/puppetlabs/puppetlabs-strings
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Puppet documentation via YARD
+test_files: []
+has_rdoc: