(PDOC-3) Change actions from module to class
Refactor the actions module so that it is a class. This is important because it allows us to keep `Puppet[]` calls out of the library and have them in the face itself. Additionally, move a few things around (like `check_required_features` since it makes require statements cleaner) and clean up some comments.
This commit is contained in:
Hailee Kenney
parent
94ff0a4445
commit
4c53f049e1
|
|
@ -1,11 +1,31 @@
|
|||
require 'puppet/face'
|
||||
require 'puppetx/puppetlabs/strings/actions'
|
||||
|
||||
include Puppetx::PuppetLabs::Strings::Actions
|
||||
|
||||
Puppet::Face.define(:strings, '0.0.1') do
|
||||
summary "Generate Puppet documentation with YARD."
|
||||
|
||||
# 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
|
||||
|
||||
# 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']
|
||||
|
||||
action(:yardoc) do
|
||||
default
|
||||
|
||||
|
|
@ -14,7 +34,8 @@ Puppet::Face.define(:strings, '0.0.1') do
|
|||
|
||||
when_invoked do |*args|
|
||||
check_required_features
|
||||
require 'puppetx/puppetlabs/strings/yard/plugin'
|
||||
|
||||
yardoc_actions = Puppetx::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
|
||||
|
||||
# The last element of the argument array should be the options hash.
|
||||
#
|
||||
|
|
@ -28,7 +49,7 @@ Puppet::Face.define(:strings, '0.0.1') do
|
|||
# and ruby files to parse.
|
||||
yard_args = (args.empty? ? MODULE_SOURCEFILES : args)
|
||||
|
||||
generate_documentation(*yard_args)
|
||||
yardoc_actions.generate_documentation(*yard_args)
|
||||
end
|
||||
end
|
||||
|
||||
|
|
@ -42,7 +63,8 @@ Puppet::Face.define(:strings, '0.0.1') do
|
|||
|
||||
when_invoked do |*args|
|
||||
check_required_features
|
||||
require 'puppetx/puppetlabs/strings/yard/plugin'
|
||||
|
||||
server_actions = Puppetx::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
|
||||
|
||||
opts = args.pop
|
||||
|
||||
|
|
@ -51,9 +73,9 @@ Puppet::Face.define(:strings, '0.0.1') do
|
|||
# FIXME: This is pretty inefficient as it forcibly re-generates the YARD
|
||||
# indicies each time the server is started. However, it ensures things are
|
||||
# generated properly.
|
||||
module_list = index_documentation_for_modules(module_names)
|
||||
module_list = server_actions.index_documentation_for_modules(module_names, MODULE_SOURCEFILES)
|
||||
|
||||
module_tuples = generate_module_tuples(module_list)
|
||||
module_tuples = server_actions.generate_module_tuples(module_list)
|
||||
|
||||
module_tuples.map! do |mod|
|
||||
[mod[:name], mod[:index_path]]
|
||||
|
|
@ -65,7 +87,7 @@ Puppet::Face.define(:strings, '0.0.1') do
|
|||
yard_args = %w[-m -q] + module_tuples.flatten
|
||||
merge_puppet_args!(yard_args)
|
||||
|
||||
serve_documentation(*yard_args)
|
||||
server_actions.serve_documentation(*yard_args)
|
||||
end
|
||||
end
|
||||
end
|
||||
|
|
|
|||
|
|
@ -1,36 +1,24 @@
|
|||
require 'puppetx/puppetlabs/strings'
|
||||
require 'puppetx/puppetlabs/strings/yard/plugin'
|
||||
|
||||
module Puppetx::PuppetLabs::Strings::Actions
|
||||
class Puppetx::PuppetLabs::Strings::Actions
|
||||
|
||||
# Creates a new instance of the Actions class by determining
|
||||
# whether or not debug and backtrace arguments should be sent
|
||||
# to YARD
|
||||
def initialize(puppet_debug, puppet_backtrace)
|
||||
@debug = puppet_debug
|
||||
@backtrace = puppet_backtrace
|
||||
end
|
||||
|
||||
# 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.unshift '--debug' if @debug
|
||||
yard_args.unshift '--backtrace' if @backtrace
|
||||
|
||||
yard_args
|
||||
end
|
||||
|
|
@ -41,20 +29,20 @@ module Puppetx::PuppetLabs::Strings::Actions
|
|||
#
|
||||
# @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)
|
||||
# @param [Array<String>] module_names a list of the module source files
|
||||
# @param [Array<String>] module_sourcefiles default list of module files
|
||||
def index_documentation_for_modules(module_names, module_sourcefiles)
|
||||
# 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
|
||||
yard_args = %w[--no-stats -n] + module_sourcefiles
|
||||
merge_puppet_args!(yard_args)
|
||||
|
||||
module_list.each do |m|
|
||||
|
|
@ -74,7 +62,7 @@ module Puppetx::PuppetLabs::Strings::Actions
|
|||
# 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
|
||||
# @param [Array<String>] module_list 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('/', '-')
|
||||
|
|
@ -87,7 +75,7 @@ module Puppetx::PuppetLabs::Strings::Actions
|
|||
# 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
|
||||
# @param [Array<String>] yard_args 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)
|
||||
|
|
@ -96,7 +84,7 @@ module Puppetx::PuppetLabs::Strings::Actions
|
|||
# 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
|
||||
# @param [Array<String>] yard_args 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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue