Class: PuppetX::PuppetLabs::Strings::Actions

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet_x/puppetlabs/strings/actions.rb

Defined Under Namespace

Classes: ModuleIndex

Instance Method Summary collapse

Constructor Details

#initialize(puppet_debug, puppet_backtrace) ⇒ Actions

Creates a new instance of the Actions class by determining whether or not debug and backtrace arguments should be sent to YARD



8
9
10
11
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 8

def initialize(puppet_debug, puppet_backtrace)
  @debug = puppet_debug
  @backtrace = puppet_backtrace
end

Instance Method Details

#generate_documentation(*yard_args) ⇒ Object

Hands off the needed information to YARD so it may generate the documentation

Parameters:

  • yard_args (Array<String>) —

    a list of all the arguments to pass to YARD



87
88
89
90
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 87

def generate_documentation(*yard_args)
  merge_puppet_args!(yard_args)
  YARD::CLI::Yardoc.run(*yard_args)
end

#generate_module_tuples(module_list) ⇒ Array<ModuleIndex>

Extracts the needed information of the modules we’re documenting

to produce documentation for. Each ModuleIndex contains the module name and the path to its YARD index

Parameters:

  • module_list (Array<String>) —

    a list of the module source files

Returns:

  • (Array<ModuleIndex>) —

    An array of representation of the modules



65
66
67
68
69
70
71
72
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 65

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

#index_documentation_for_modules(module_names, module_sourcefiles) ⇒ Array<Module>

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.

Parameters:

  • module_names (Array<String>) —

    a list of the module source files

  • module_sourcefiles (Array<String>) —

    default list of module files

Returns:

  • (Array<Module>) —

    the modules to be documented



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 33

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

  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

#merge_puppet_args!(yard_args) ⇒ Object

Maps things like the Puppet ‘–debug` flag to YARD options.



18
19
20
21
22
23
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 18

def merge_puppet_args!(yard_args)
  yard_args.unshift '--debug'     if @debug
  yard_args.unshift '--backtrace' if @backtrace

  yard_args
end

#serve_documentation(*yard_args) ⇒ Object

Hands off the needed information to YARD so it may serve the documentation

Parameters:

  • yard_args (Array<String>) —

    a list of all the arguments to pass to YARD



78
79
80
81
 
# File 'lib/puppet_x/puppetlabs/strings/actions.rb', line 78

def serve_documentation(*yard_args)
  merge_puppet_args!(yard_args)
  YARD::CLI::Server.run(*yard_args)
end