Add a modules action to the yardoc face

This commit adds the `puppet yardoc modules` action which is designed to
process Puppet Modules in the same way `yard gems` processes Ruby Gems. This
action walks the list of modules generated by `puppet module list` and
generates a YARD index (.yardoc directory) in each module root. This index
contains all the data required to generate documentation using other YARD
tools.

lib/puppet/face/yardoc.rb

@@ -3,13 +3,7 @@ require 'puppet/face'
 Puppet::Face.define(:yardoc, '0.0.1') do
   summary "Generate Puppet documentation with YARD."
 
-  action(:yardoc) do
+  def check_required_features
-    default
-
-    summary "Generate module documentation."
-    arguments "[manifest_file.pp ...]"
-
-    when_invoked do |*args|
     unless Puppet.features.yard?
       raise RuntimeError, "The 'yard' gem must be installed in order to use this face."
     end
@@ -21,6 +15,23 @@ Puppet::Face.define(:yardoc, '0.0.1') do
     if RUBY_VERSION < '1.9' && !Puppet.features.require_relative?
       raise RuntimeError, "The 'backports' gem must be installed in order to use this face under Ruby 1.8.7."
     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']
+
+  action(:yardoc) do
+    default
+
+    summary "Generate YARD documentation from files."
+    arguments "[manifest_file.pp ...]"
+
+    when_invoked do |*args|
+      check_required_features
 
       # The last element of the argument array should be the options hash.
       #
@@ -32,7 +43,7 @@ Puppet::Face.define(:yardoc, '0.0.1') do
 
       # For now, assume the remaining positional args are a list of manifest
       # files to parse.
-      manifest_files = (args.empty? ? ['manifests/**/*.pp'] : args)
+      manifest_files = (args.empty? ? MODULE_SOURCEFILES : args)
 
       require 'puppetx/yardoc/yard/plugin'
 
@@ -40,4 +51,38 @@ Puppet::Face.define(:yardoc, '0.0.1') do
       YARD::CLI::Yardoc.run(*manifest_files)
     end
   end
+
+  # NOTE: Modeled after the `yard gems` command which builds doc indicies
+  # (.yardoc directories) for Ruby Gems. Currently lacks the fine-grained
+  # control over where these indicies are created and just dumps them in the
+  # module roots.
+  action(:modules) do
+    summary "Generate YARD indices for a list of modules."
+    arguments "[module-name ...]"
+
+    when_invoked do |*args|
+      check_required_features
+      require 'puppetx/yardoc/yard/plugin'
+      opts = args.pop
+
+      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 = module_list.select {|m| args.include? m.name} unless args.empty?
+
+      module_list.each do |m|
+        Dir.chdir(m.path) do
+          # 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::CLI::Yardoc.run('--no-stats', '-n', *MODULE_SOURCEFILES)
+
+          # Cear the global Registry so that objects from one module don't
+          # bleed into the next.
+          YARD::Registry.clear
+        end
+      end
+    end
+  end
 end