1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# frozen_string_literal: true
# The root module for Puppet Strings.
module PuppetStrings
# The glob patterns used to search for files to document.
DEFAULT_SEARCH_PATTERNS = ['manifests/**/*.pp', 'functions/**/*.pp', 'types/**/*.pp', 'lib/**/*.rb', 'tasks/*.json', 'plans/**/*.pp'].freeze
# 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]
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
def self.puppet_5?
Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0
end
def self.render_json(path)
require 'puppet-strings/json'
PuppetStrings::Json.render(path)
end
def self.render_markdown(path)
require 'puppet-strings/markdown'
PuppetStrings::Markdown.render(path)
end
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
# Runs the YARD documentation server.
# @param [Array<String>] args The arguments to YARD.
def self.run_server(*args)
require 'puppet-strings/yard'
PuppetStrings::Yard.setup!
YARD::CLI::Server.run(*args)
end
end
|
