From e2a9e40f01aef9740458d5497c72d2b61182461e Mon Sep 17 00:00:00 2001
From: Charlie Sharpsteen <source@sharpsteen.net>
Date: Sun, 1 Jun 2014 12:33:34 -0700
Subject: [PATCH] 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 | 71 ++++++++++++++++++++++++++++++++-------
 1 file changed, 58 insertions(+), 13 deletions(-)

diff --git a/lib/puppet/face/yardoc.rb b/lib/puppet/face/yardoc.rb
index 6b50985..fe372b4 100644
--- a/lib/puppet/face/yardoc.rb
+++ b/lib/puppet/face/yardoc.rb
@@ -3,24 +3,35 @@ require 'puppet/face'
 Puppet::Face.define(:yardoc, '0.0.1') do
   summary "Generate Puppet documentation with YARD."
 
+  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 < '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 module documentation."
+    summary "Generate YARD documentation from files."
     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
-
-      unless Puppet.features.rgen?
-        raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
-      end
-
-      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
+      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