(PDOC-184) generate markdown

This change does a few things:
1. Fixes up new api handler to return the stuff we want
2. Adds all the logic to parse YARD registries into markdown
3. Adds templates for markdown
4. Changes Face cli to use a --format option that can be used for either
markdown or json

Author: eputnam

lib/puppet-strings.rb

@@ -14,7 +14,9 @@ module PuppetStrings
   # @option options [Boolean] :debug Enable YARD debug output.
   # @option options [Boolean] :backtrace Enable YARD backtraces.
   # @option options [String] :markup The YARD markup format to use (defaults to 'markdown').
-  # @option options [String] :json Enables JSON output to the given file. If the file is nil, STDOUT is used.
+  # @option options [String] :format Specify output format (markdown or json)
+  # @option options [String] :path Write the selected format to a file path
+  # @option options [Boolean] :stdout Use this switch to pipe the selected format to STDOUT
   # @option options [Array<String>] :yard_args The arguments to pass to yard.
   # @return [void]
   def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
@@ -27,15 +29,13 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
     args << '--backtrace' if options[:backtrace]
     args << "-m#{options[:markup] || 'markdown'}"
 
-    render_as_json = options.key? :json
-    json_file = nil
-    if render_as_json
-      json_file = options[:json]
+    if options[:json] || options[:markdown]
+      file = options[:path]
       # Disable output and prevent stats/progress when writing to STDOUT
       args << '-n'
-      args << '-q' unless json_file
-      args << '--no-stats' unless json_file
-      args << '--no-progress' unless json_file
+      args << '-q' unless file
+      args << '--no-stats' unless file
+      args << '--no-progress' unless file
     end
 
     yard_args = options[:yard_args]
@@ -46,10 +46,24 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
     YARD::CLI::Yardoc.run(*args)
 
     # If outputting JSON, render the output
-    if render_as_json
-      require 'puppet-strings/json'
-      PuppetStrings::Json.render(json_file)
+    if options[:json]
+      render_json(options[:path])
     end
+
+    # If outputting Markdown, render the output
+    if options[:markdown]
+      render_markdown(options[:path])
+    end
+  end
+
+  def self.render_json(path)
+    require 'puppet-strings/json'
+    PuppetStrings::Json.render(path)
+  end
+
+  def self.render_markdown(path)
+    require 'puppet-strings/markdown'
+    PuppetStrings::Markdown.render(path)
   end
 
   # Runs the YARD documentation server.

lib/puppet-strings/markdown.rb

@@ -0,0 +1,32 @@
+require 'puppet-strings/json'
+
+# module for parsing Yard Registries and generating markdown
+module PuppetStrings::Markdown
+  require_relative 'markdown/puppet_classes'
+  require_relative 'markdown/puppet_functions'
+  require_relative 'markdown/puppet_defined_types'
+  require_relative 'markdown/puppet_resource_types'
+  require_relative 'markdown/table_of_contents'
+
+  # generates markdown documentation
+  # @return [String] markdown doc
+  def self.generate
+    final = "# Reference\n\n"
+    final << PuppetStrings::Markdown::TableOfContents.render
+    final << PuppetStrings::Markdown::PuppetClasses.render
+    final << PuppetStrings::Markdown::PuppetDefinedTypes.render
+    final << PuppetStrings::Markdown::PuppetResourceTypes.render
+    final << PuppetStrings::Markdown::PuppetFunctions.render
+
+    final
+  end
+
+  def self.render(path = nil)
+    if path.nil?
+      puts generate
+      exit
+    else
+      File.open(path, 'w') { |file| file.write(generate) }
+    end
+  end
+end

lib/puppet-strings/markdown/base.rb

@@ -0,0 +1,84 @@
+require 'puppet-strings'
+require 'puppet-strings/json'
+require 'puppet-strings/yard'
+
+module PuppetStrings::Markdown
+  class Base
+    def initialize(registry, component_type)
+      @type = component_type
+      @registry = registry
+      @tags = registry[:docstring][:tags] || []
+    end
+
+    def name
+      @registry[:name].to_s unless @registry[:name].nil?
+    end
+
+    def text
+      @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
+    end
+
+    def return_val
+      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
+    end
+
+    def return_type
+      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
+    end
+
+    # @return [String] text from @since tag
+    def since
+      @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
+    end
+
+    # return [Array] array of @see tag hashes
+    def see
+      @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
+    end
+
+    # return [String] text from @summary tag
+    def summary
+      @tags.select { |tag| tag[:tag_name] == 'summary' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'summary' }[0].nil?
+    end
+
+    # return [Array] array of parameter tag hashes
+    def params
+      @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
+    end
+
+    # return [Array] array of example tag hashes
+    def examples
+      @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
+    end
+
+    def toc_info
+      {
+        name: name.to_s,
+        link: link,
+        desc: summary || @registry[:docstring][:text].gsub("\n", ". ")
+      }
+    end
+
+    def link
+      name.delete('::').strip.gsub(' ','-').downcase
+    end
+
+    def defaults
+      @registry[:defaults] unless @registry[:defaults].nil?
+    end
+
+    def value_string(value)
+      to_symbol = %w[undef true false]
+      if to_symbol.include? value
+        return "`#{value}`"
+      else
+        return value
+      end
+    end
+
+    def render(template)
+      file = File.join(File.dirname(__FILE__),"templates/#{template}")
+      ERB.new(File.read(file), nil, '-').result(binding)
+    end
+  end
+end

lib/puppet-strings/markdown/puppet_class.rb

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

lib/puppet-strings/markdown/puppet_classes.rb

@@ -0,0 +1,27 @@
+require_relative 'puppet_class'
+
+module PuppetStrings::Markdown
+  module PuppetClasses
+    def self.in_classes
+      YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
+    end
+
+    def self.render
+      final = "## Classes\n\n"
+      in_classes.each do |klass|
+        final << PuppetStrings::Markdown::PuppetClass.new(klass).render
+      end
+      final
+    end
+
+    def self.toc_info
+      final = []
+
+      in_classes.each do |klass|
+        final.push(PuppetStrings::Markdown::PuppetClass.new(klass).toc_info)
+      end
+
+      final
+    end
+  end
+end

lib/puppet-strings/markdown/puppet_defined_type.rb

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

lib/puppet-strings/markdown/puppet_defined_types.rb

@@ -0,0 +1,27 @@
+require_relative 'puppet_defined_type'
+
+module PuppetStrings::Markdown
+  module PuppetDefinedTypes
+    def self.in_dtypes
+      YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
+    end
+
+    def self.render
+      final = "## Defined types\n\n"
+      in_dtypes.each do |type|
+        final << PuppetStrings::Markdown::PuppetDefinedType.new(type).render
+      end
+      final
+    end
+
+    def self.toc_info
+      final = []
+
+      in_dtypes.each do |type|
+        final.push(PuppetStrings::Markdown::PuppetDefinedType.new(type).toc_info)
+      end
+
+      final
+    end
+  end
+end

lib/puppet-strings/markdown/puppet_function.rb

@@ -0,0 +1,31 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class PuppetFunction < Base
+    attr_reader :signatures
+
+    def initialize(registry)
+      @template = 'puppet_function.erb'
+      super(registry, 'function')
+      @signatures = []
+      registry[:signatures].each do |sig|
+        @signatures.push(Signature.new(sig))
+      end
+    end
+
+    def render
+      super(@template)
+    end
+  end
+
+  class PuppetFunction::Signature < Base
+    def initialize(registry)
+      @registry = registry
+      super(@registry, 'function signature')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
+end

lib/puppet-strings/markdown/puppet_functions.rb

@@ -0,0 +1,28 @@
+require_relative 'puppet_function'
+
+module PuppetStrings::Markdown
+  module PuppetFunctions
+    def self.in_functions
+      YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
+    end
+
+    def self.render
+      final = "## Functions\n\n"
+      in_functions.each do |func|
+        final << PuppetStrings::Markdown::PuppetFunction.new(func).render
+      end
+      final
+    end
+
+    def self.toc_info
+      final = []
+
+      in_functions.each do |func|
+        final.push(PuppetStrings::Markdown::PuppetFunction.new(func).toc_info)
+      end
+
+      final
+    end
+  end
+end
+

lib/puppet-strings/markdown/puppet_resource_type.rb

@@ -0,0 +1,26 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  class PuppetResourceType < Base
+    def initialize(registry)
+      @template = 'puppet_resource_type.erb'
+      super(registry, 'resource type')
+    end
+
+    def render
+      super(@template)
+    end
+
+    def properties
+      @registry[:properties]
+    end
+
+    def parameters
+      @registry[:parameters]
+    end
+
+    def regex_in_data_type?(data_type)
+      data_type.match(/\w+\[\/.*\/\]/).length > 0
+    end
+  end
+end