Module: PuppetStrings

Defined in:
lib/puppet-strings.rb,
lib/puppet-strings/tasks.rb

Overview

The root module for Puppet Strings.

Defined Under Namespace

Modules: Json, Tasks, Yard

Constant Summary collapse

DEFAULT_SEARCH_PATTERNS =

The glob patterns used to search for files to document.

%w(
  manifests/**/*.pp
  functions/**/*.pp
  types/**/*.pp
  lib/**/*.rb
).freeze

Class Method Summary collapse

Class Method Details

.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {}) ⇒ void

This method returns an undefined value.

Generates documentation.

Parameters:

  • search_patterns (Array<String>) (defaults to: DEFAULT_SEARCH_PATTERNS) —

    The search patterns (e.g. manifests/*/.pp) to look for files.

  • options (Hash) (defaults to: {}) —

    The options hash.

Options Hash (options):

  • :debug (Boolean) —

    Enable YARD debug output.

  • :backtrace (Boolean) —

    Enable YARD backtraces.

  • :markup (String) —

    The YARD markup format to use (defaults to ‘markdown’).

  • :json (String) —

    Enables JSON output to the given file. If the file is nil, STDOUT is used.

  • :yard_args (Array<String>) —

    The arguments to pass to yard.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/puppet-strings.rb', line 20

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

  # Format the arguments to YARD
  args = ['doc']
  args << '--debug'     if options[:debug]
  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]
    # 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
  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
  if render_as_json
    require 'puppet-strings/json'
    PuppetStrings::Json.render(json_file)
  end
end

.run_server(*args) ⇒ Object

Runs the YARD documentation server.

Parameters:

  • args (Array<String>) —

    The arguments to YARD.



57
58
59
60
61
62
 
# File 'lib/puppet-strings.rb', line 57

def self.run_server(*args)
  require 'puppet-strings/yard'
  PuppetStrings::Yard.setup!

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