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)
  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
    ERB.new(File.read(path), trim_mode: '-')
  else
    # This outputs warnings in Ruby 2.6+.
    ERB.new(File.read(path), nil, '-')
  end
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 { |item| item.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 { |item| item.private? }
    unless items.empty?
      output << "## #{group.group_name}\n\n"
      output.append(items.map { |item| item.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.open(path, 'w') { |file| file.write(generate) }
    YARD::Logger.instance.debug "Wrote markdown to #{path}"
  end
end