module PuppetStrings::Markdown

module for parsing Yard Registries and generating markdown

Implements classes that make elements in a YARD::Registry hash easily accessible for template.

Public Class Methods

erb(path) click to toggle source

Helper function to load an ERB template.

@param [String] path The full path to the template file. @return [ERB] Template

# File lib/puppet-strings/markdown.rb, line 78
def self.erb(path)
  ERB.new(File.read(path), trim_mode: '-')
end
generate() click to toggle source

generates markdown documentation @return [String] markdown doc

# File lib/puppet-strings/markdown.rb, line 32
def self.generate
  output = [
    "# Reference\n\n",
    "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
    "## Table of Contents\n\n"
  ]

  # Create table of contents
  template = erb(File.join(__dir__, 'markdown', 'templates', 'table_of_contents.erb'))
  groups.each do |group|
    group_name = group.group_name
    items = group.items.map(&:toc_info)
    has_private = items.any? { |item| item[:private] }
    has_public = items.any? { |item| !item[:private] }

    output << template.result(binding)
  end

  # Create actual contents
  groups.each do |group|
    items = group.items.reject(&:private?)
    unless items.empty?
      output << "## #{group.group_name}\n\n"
      output.append(items.map(&:render))
    end
  end

  output.join
end
groups() click to toggle source

Get classes that handle collecting and rendering each section/group.

@return [Array] The classes

# File lib/puppet-strings/markdown.rb, line 18
def self.groups
  [
    PuppetStrings::Markdown::PuppetClass,
    PuppetStrings::Markdown::DefinedType,
    PuppetStrings::Markdown::ResourceType,
    PuppetStrings::Markdown::Function,
    PuppetStrings::Markdown::DataType,
    PuppetStrings::Markdown::PuppetTask,
    PuppetStrings::Markdown::PuppetPlan
  ]
end
render(path = nil) click to toggle source

mimicks the behavior of the json render, although path will never be nil @param [String] path path to destination file

# File lib/puppet-strings/markdown.rb, line 64
def self.render(path = nil)
  if path.nil?
    puts generate
    exit
  else
    File.write(path, generate)
    YARD::Logger.instance.debug "Wrote markdown to #{path}"
  end
end