Module: PuppetStrings

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

Overview

Ensure PuppetStrings is loaded.

Defined Under Namespace

Modules: Describe, Json, Markdown, Tasks, Yard

Constant Summary collapse

DEFAULT_SEARCH_PATTERNS =

The glob patterns used to search for files to document.

['manifests/**/*.pp', 'functions/**/*.pp', 'types/**/*.pp', 'lib/**/*.rb', 'tasks/*.json', 'plans/**/*.pp'].freeze
VERSION = 
'4.1.3'

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’).

  • :path (String) —

    Write the selected format to a file path

  • :markdown (Boolean) —

    From the –format option, is the format Markdown?

  • :json (Boolean) —

    Is the format JSON?

  • :yard_args (Array<String>) —

    The arguments to pass to yard.



19
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
54
55
56
57
58
59
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


61
62
63
 
# 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) ⇒ Object 



75
76
77
78
 
# 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) ⇒ Object 



65
66
67
68
 
# File 'lib/puppet-strings.rb', line 65

def self.render_json(path)
  require 'puppet-strings/json'
  PuppetStrings::Json.render(path)
end

.render_markdown(path) ⇒ Object 



70
71
72
73
 
# File 'lib/puppet-strings.rb', line 70

def self.render_markdown(path)
  require 'puppet-strings/markdown'
  PuppetStrings::Markdown.render(path)
end

.run_server(*args) ⇒ Object

Runs the YARD documentation server.

Parameters:

  • args (Array<String>) —

    The arguments to YARD.



82
83
84
85
86
87
 
# 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