module PuppetStrings

The root module for Puppet Strings.

Ensure PuppetStrings is loaded.

Constants

DEFAULT_SEARCH_PATTERNS

The glob patterns used to search for files to document.

VERSION

Public Class Methods

generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {}) click to toggle source

Generates documentation. @param [Array<String>] search_patterns The search patterns (e.g. manifests/*/.pp) to look for files. @param [Hash] options The options hash. @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] :path Write the selected format to a file path @option options [Boolean] :markdown From the –format option, is the format Markdown? @option options [Boolean] :json Is the format JSON? @option options [Array<String>] :yard_args The arguments to pass to yard. @return [void]

# File lib/puppet-strings.rb, line 19
def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
  require 'puppet-strings/yard'
  PuppetStrings::Yard.setup!

  # Format the arguments to YARD
  args = ['doc']
  args << '--no-progress'
  args << '--debug'     if options[:debug]
  args << '--backtrace' if options[:debug]
  args << "-m#{options[:markup] || 'markdown'}"

  file = nil
  if options[:json] || options[:markdown]
    file = if options[:json]
             options[:path]
           elsif options[:markdown]
             options[:path] || 'REFERENCE.md'
           end
    # Disable output and prevent stats/progress when writing to STDOUT
    args << '-n'
    args << '-q' unless file
    args << '--no-stats' unless file
  end

  yard_args = options[:yard_args]
  args += yard_args if yard_args
  args += search_patterns

  # Run YARD
  YARD::CLI::Yardoc.run(*args)

  # If outputting JSON, render the output
  render_json(file) if options[:json] && !options[:describe]

  # If outputting Markdown, render the output
  render_markdown(file) if options[:markdown]

  return unless options[:describe]

  render_describe(options[:describe_types], options[:describe_list], options[:providers], options[:list_providers])
end
puppet_5?() click to toggle source
# File lib/puppet-strings.rb, line 61
def self.puppet_5?
  Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0
end
render_describe(describe_types, list = false, show_providers = true, list_providers = false) click to toggle source
# File lib/puppet-strings.rb, line 75
def self.render_describe(describe_types, list = false, show_providers = true, list_providers = false)
  require 'puppet-strings/describe'
  PuppetStrings::Describe.render(describe_types, list, show_providers, list_providers)
end
render_json(path) click to toggle source
# File lib/puppet-strings.rb, line 65
def self.render_json(path)
  require 'puppet-strings/json'
  PuppetStrings::Json.render(path)
end
render_markdown(path) click to toggle source
# File lib/puppet-strings.rb, line 70
def self.render_markdown(path)
  require 'puppet-strings/markdown'
  PuppetStrings::Markdown.render(path)
end
run_server(*args) click to toggle source

Runs the YARD documentation server. @param [Array<String>] args The arguments to YARD.

# File lib/puppet-strings.rb, line 82
def self.run_server(*args)
  require 'puppet-strings/yard'
  PuppetStrings::Yard.setup!

  YARD::CLI::Server.run(*args)
end