106 lines
3.6 KiB
Ruby
106 lines
3.6 KiB
Ruby
require 'puppetx/puppetlabs/strings'
|
|
|
|
module Puppetx::PuppetLabs::Strings::Actions
|
|
|
|
# Holds the name of a module and the file path to its YARD index
|
|
ModuleIndex = Struct.new(:name, :index_path)
|
|
|
|
# A list of globs that generates the default list of module files from which
|
|
# documentation can be extracted.
|
|
#
|
|
# TODO: It would be awesome if we could somehow override/append to the
|
|
# default file list that YARD uses. Consider an upstream PR for this.
|
|
MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb']
|
|
|
|
# Ensures that the user has the needed features to use puppet strings
|
|
def check_required_features
|
|
unless Puppet.features.yard?
|
|
raise RuntimeError, "The 'yard' gem must be installed in order to use this face."
|
|
end
|
|
|
|
unless Puppet.features.rgen?
|
|
raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
|
|
end
|
|
|
|
if RUBY_VERSION.match(/^1\.8/)
|
|
raise RuntimeError, "This face requires Ruby 1.9 or greater."
|
|
end
|
|
end
|
|
|
|
# Maps things like the Puppet `--debug` flag to YARD options.
|
|
def merge_puppet_args!(yard_args)
|
|
yard_args.unshift '--debug' if Puppet[:debug]
|
|
yard_args.unshift '--backtrace' if Puppet[:trace]
|
|
|
|
yard_args
|
|
end
|
|
|
|
# Builds doc indices (.yardoc directories) for modules.
|
|
# Currently lacks the fine-grained control over where these
|
|
# indices are created and just dumps them in the module roots.
|
|
#
|
|
# @return [Array<Module>] the modules to be documented
|
|
#
|
|
# @param [Array<String>] a list of the module source files
|
|
def index_documentation_for_modules(module_names)
|
|
# NOTE: The return value of the `module` Face seems to have changed in
|
|
# 3.6.x. This part of the code will blow up if run under an earlier
|
|
# version of Puppet.
|
|
modules = Puppet::Face[:module, :current].list
|
|
module_list = modules[:modules_by_path].values.flatten
|
|
|
|
# TODO: Can use select! if Ruby 1.8.7 support is dropped.
|
|
module_list.select! {|m| module_names.include? m.name} unless module_names.empty?
|
|
|
|
# Invoke `yardoc` with -n so that it doesn't generate any HTML output but
|
|
# does build a `.yardoc` index that other tools can generate output from.
|
|
yard_args = %w[--no-stats -n] + MODULE_SOURCEFILES
|
|
merge_puppet_args!(yard_args)
|
|
|
|
module_list.each do |m|
|
|
Dir.chdir(m.path) do
|
|
YARD::CLI::Yardoc.run(*yard_args)
|
|
|
|
# Clear the global Registry so that objects from one module don't
|
|
# bleed into the next.
|
|
YARD::Registry.clear
|
|
end
|
|
end
|
|
end
|
|
|
|
# Extracts the needed information of the modules we're documenting
|
|
#
|
|
# @return [Array<ModuleIndex>] An array of representation of the modules
|
|
# to produce documentation for. Each ModuleIndex contains the module name
|
|
# and the path to its YARD index
|
|
#
|
|
# @param [Array<String>] a list of the module source files
|
|
def generate_module_tuples(module_list)
|
|
module_list.map do |mod|
|
|
name = (mod.forge_name || mod.name).gsub('/', '-')
|
|
yard_index = File.join(mod.path, '.yardoc')
|
|
|
|
ModuleIndex.new(name, yard_index)
|
|
end
|
|
end
|
|
|
|
# Hands off the needed information to YARD so it may
|
|
# serve the documentation
|
|
#
|
|
# @param [Array<String>] a list of all the arguments to pass to YARD
|
|
def serve_documentation(*yard_args)
|
|
merge_puppet_args!(yard_args)
|
|
YARD::CLI::Server.run(*yard_args)
|
|
end
|
|
|
|
# Hands off the needed information to YARD so it may
|
|
# generate the documentation
|
|
#
|
|
# @param [Array<String>] a list of all the arguments to pass to YARD
|
|
def generate_documentation(*yard_args)
|
|
merge_puppet_args!(yard_args)
|
|
YARD::CLI::Yardoc.run(*yard_args)
|
|
end
|
|
end
|
|
|