(PDOC-226) Add Puppet Data Type documentation

Previously Puppet-Strings could not document Ruby Data Types. This commit:

* Updates the ruby handler to receive `Puppet::DataTypes.create_type` method
  invocations and document the call site.  The documention is similar to that
  of a puppet custom type.
* Adds tests for ruby parsing to ensure the Yard Code Object is populated
  correctly
* Adds support for JSON, Markdown and HTML rendering.
* Adds tests for JSON and Markdown rendering

Author: glennsarti

JSON.md

@@ -9,11 +9,12 @@ puppet strings generate --format json
 Document Schema
 ===============
 
-At the top level, there are seven arrays in the JSON document:
+At the top level, there are eight arrays in the JSON document:
 
 | Document Key     | Description                                                                   |
 | ---------------- | ----------------------------------------------------------------------------- |
 | puppet_classes   | The list of Puppet classes that were parsed.                                  |
+| data_types       | The list of data types that were parsed.                                      |
 | defined_types    | The list of defined types that were parsed.                                   |
 | resource_types   | The list of resource types that were parsed.                                  |
 | providers        | The list of resource providers that were parsed.                              |
@@ -36,6 +37,20 @@ Each entry in the `puppet_classes` list is an object with the following attribut
 | defaults      | The map of parameter names to default values.         |
 | source        | The Puppet source code for the class.                 |
 
+Data Types
+----------
+
+Each entry in the `data_types` list is an object with the following attributes:
+
+| Attribute Key | Description                                                 |
+| ------------- | ----------------------------------------------------------- |
+| name          | The name of the data type.                                  |
+| file          | The file defining the data type.                            |
+| line          | The line where the data type is data.                       |
+| docstring     | The *DocString* object for the data type (see below).       |
+| defaults      | The map of parameter names to default values.               |
+| source        | The ruby source code for the data type. (Not Implemented)   |
+
 Defined Types
 -------------
 

lib/puppet-strings/json.rb

@@ -8,6 +8,7 @@ module PuppetStrings::Json
   def self.render(file = nil)
     document = {
       puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash),
+      data_types: YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash),
       defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
       resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
       providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash),

lib/puppet-strings/markdown.rb

@@ -5,6 +5,7 @@ module PuppetStrings::Markdown
   require_relative 'markdown/puppet_classes'
   require_relative 'markdown/functions'
   require_relative 'markdown/defined_types'
+  require_relative 'markdown/data_types'
   require_relative 'markdown/resource_types'
   require_relative 'markdown/puppet_tasks'
   require_relative 'markdown/puppet_plans'
@@ -20,6 +21,7 @@ def self.generate
     final << PuppetStrings::Markdown::DefinedTypes.render
     final << PuppetStrings::Markdown::ResourceTypes.render
     final << PuppetStrings::Markdown::Functions.render
+    final << PuppetStrings::Markdown::DataTypes.render
     final << PuppetStrings::Markdown::PuppetTasks.render
     final << PuppetStrings::Markdown::PuppetPlans.render
 

lib/puppet-strings/markdown/data_type.rb

@@ -0,0 +1,14 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class DataType < Base
+    def initialize(registry)
+      @template = 'data_type.erb'
+      super(registry, 'data type')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

lib/puppet-strings/markdown/data_types.rb

@@ -0,0 +1,38 @@
+require_relative 'data_type'
+
+module PuppetStrings::Markdown
+  module DataTypes
+
+    # @return [Array] list of data types
+    def self.in_dtypes
+      arr = YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::DataType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_dtypes.nil?
+        in_dtypes.find { |type| type.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
+      in_dtypes.each do |type|
+        final << type.render unless type.private?
+      end
+      final
+    end
+
+
+    def self.toc_info
+      final = ["Data types"]
+
+      in_dtypes.each do |type|
+        final.push(type.toc_info)
+      end
+
+      final
+    end
+  end
+end

lib/puppet-strings/markdown/table_of_contents.rb

@@ -7,6 +7,7 @@ def self.render
       PuppetStrings::Markdown::DefinedTypes,
       PuppetStrings::Markdown::ResourceTypes,
       PuppetStrings::Markdown::Functions,
+      PuppetStrings::Markdown::DataTypes,
       PuppetStrings::Markdown::PuppetTasks,
       PuppetStrings::Markdown::PuppetPlans].each do |r|
         toc = r.toc_info

lib/puppet-strings/markdown/templates/data_type.erb

@@ -0,0 +1,74 @@
+### <%= name %>
+
+<% if text -%>
+<%= text %>
+<% elsif summary -%>
+<%= summary %>
+<% else -%>
+<%= "The #{name} data type." %>
+<% end -%>
+
+<% if todo -%>
+* **TODO** <%= todo %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if since -%>
+* **Since** <%= since %>
+
+<% end -%>
+<% if see -%>
+* **See also**
+<% see.each do |sa| -%>
+<% if sa[:name] -%>
+<%= sa[:name] %>
+<% end -%>
+<% if sa[:text] -%>
+<%= sa[:text] %>
+<% end -%>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+#### Examples
+
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+#### Parameters
+
+The following parameters are available in the `<%= name %>` <%= @type %>.
+
+<% params.each do |param| -%>
+##### `<%= param[:name] %>`
+
+<% if param[:types] -%>
+Data type: `<%= param[:types].join(', ') -%>`
+
+<% end -%>
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if defaults && defaults[param[:name]] -%>
+Default value: <%= value_string(defaults[param[:name]]) %>
+
+<% end -%>
+<% end -%>
+<% end -%>

lib/puppet-strings/yard.rb

@@ -46,6 +46,7 @@ def all_objects
       :module,
       :class,
       :puppet_class,
+      :puppet_data_type,
       :puppet_defined_type,
       :puppet_type,
       :puppet_provider,
@@ -64,6 +65,10 @@ def stats_for_puppet_classes
     output 'Puppet Classes', *type_statistics_all(:puppet_class)
   end
 
+  def stats_for_puppet_data_types
+    output 'Puppet Data Types', *type_statistics_all(:puppet_data_type)
+  end
+
   def stats_for_puppet_defined_types
     output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type)
   end

lib/puppet-strings/yard/code_objects.rb

@@ -1,6 +1,7 @@
 # The module for custom YARD code objects.
 module PuppetStrings::Yard::CodeObjects
   require 'puppet-strings/yard/code_objects/class'
+  require 'puppet-strings/yard/code_objects/data_type'
   require 'puppet-strings/yard/code_objects/defined_type'
   require 'puppet-strings/yard/code_objects/type'
   require 'puppet-strings/yard/code_objects/provider'

lib/puppet-strings/yard/code_objects/data_type.rb

@@ -0,0 +1,80 @@
+require 'puppet-strings/yard/code_objects/group'
+require 'puppet-strings/yard/util'
+
+# Implements the group for Puppet DataTypes.
+class PuppetStrings::Yard::CodeObjects::DataTypes < PuppetStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_types)
+  end
+
+  # Gets the display name of the group.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
+  # @return [String] Returns the display name of the group.
+  def name(prefix = false)
+    'Puppet Data Types'
+  end
+end
+
+# Implements the Puppet DataType code object.
+class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObjects::Base
+  # Initializes a Puppet class code object.
+  # @param [String] The name of the Data Type
+  # @return [void]
+  def initialize(name)
+    super(PuppetStrings::Yard::CodeObjects::DataTypes.instance, name)
+    @parameters = []
+    @defaults = {}
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  def parameter_exist?(name)
+    !docstring.tags(:param).find { |item| item.name == name }.nil?
+  end
+
+  def add_parameter(name, type, default)
+    tag = docstring.tags(:param).find { |item| item.name == name }
+    if tag.nil?
+      tag = YARD::Tags::Tag.new(:param, '', nil, name)
+      docstring.add_tag(tag)
+    end
+    type = [type] unless type.is_a?(Array)
+    tag.types = type if tag.types.nil?
+    set_parameter_default(name, default)
+  end
+
+  def set_parameter_default(param_name, default)
+    defaults.delete(param_name)
+    defaults[param_name] = default unless default.nil?
+  end
+
+  def parameters
+    docstring.tags(:param).map { |tag| [tag.name, defaults[tag.name]] }
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:defaults] = defaults unless defaults.empty?
+    hash[:source] = source unless source && source.empty?
+    hash
+  end
+end

lib/puppet-strings/yard/handlers.rb

@@ -2,6 +2,7 @@
 module PuppetStrings::Yard::Handlers
   # The module for custom Ruby YARD handlers.
   module Ruby
+    require 'puppet-strings/yard/handlers/ruby/data_type_handler'
     require 'puppet-strings/yard/handlers/ruby/type_handler'
     require 'puppet-strings/yard/handlers/ruby/type_extras_handler'
     require 'puppet-strings/yard/handlers/ruby/rsapi_handler'