Move Puppet classes into a custom namespace

Instead of documenting Puppet classes using `ClassObject`, use a custom
subclass of `NamespaceObject`. This is done because Puppet classes are not Ruby
classes and will have components that don't fit into the model offered by
`ClassObject`.

This commit also adds a couple of monkey patches to integrate the new
`:hostclass` into YARD tooling and the beginnings of some custom templating.

lib/puppetx/yardoc/yard/code_objects.rb

@@ -0,0 +1 @@
+require_relative 'code_objects/host_class_object'

lib/puppetx/yardoc/yard/code_objects/host_class_object.rb

@@ -0,0 +1,10 @@
+require 'yard'
+require 'puppet/pops'
+
+require_relative '../../../yardoc'
+
+module Puppetx::Yardoc::YARD::CodeObjects
+  class HostClassObject < YARD::CodeObjects::NamespaceObject
+    # Nothing to see here yet...
+  end
+end

lib/puppetx/yardoc/yard/handlers/base.rb

@@ -2,10 +2,14 @@ require 'yard'
 require 'puppet/pops'
 
 require_relative '../../../yardoc'
+require_relative '../code_objects'
 
 module Puppetx::Yardoc::YARD::Handlers
   class Base < YARD::Handlers::Base
-    include Puppet::Pops::Model # This allows handlers to match based on model classes.
+    # Easy access to Pops model objects for handler matching.
+    include Puppet::Pops::Model
+    # Easy access to custom code objects from which documentation is generated.
+    include Puppetx::Yardoc::YARD::CodeObjects
 
     def self.handles?(statement)
       handlers.any? {|h| h == statement.type}

lib/puppetx/yardoc/yard/handlers/host_class_handler.rb

@@ -5,7 +5,7 @@ module Puppetx::Yardoc::YARD::Handlers
     handles HostClassDefinition
 
     process do
-      register YARD::CodeObjects::ClassObject.new(:root, statement.pops_obj.name)
+      register HostClassObject.new(:root, statement.pops_obj.name)
     end
   end
 end

lib/puppetx/yardoc/yard/monkey_patches.rb

@@ -0,0 +1,17 @@
+require 'yard'
+
+# TODO: As far as I can tell, monkeypatching is the officially recommended way
+# to extend these tools to cover custom usecases. Follow up on the YARD mailing
+# list or IRC to see if there is a better way.
+
+class YARD::CLI::Yardoc
+  def all_objects
+    YARD::Registry.all(:root, :module, :class, :hostclass)
+  end
+end
+
+class YARD::CLI::Stats
+  def stats_for_hostclasses
+    output 'Puppet Classes', *type_statistics(:hostclass)
+  end
+end

lib/puppetx/yardoc/yard/plugin.rb

@@ -3,6 +3,7 @@ if RUBY_VERSION < '1.9'
   require 'backports/1.9.1/kernel/require_relative'
 end
 
+require_relative 'monkey_patches'
 require_relative 'parser'
 require_relative 'handlers'
 
@@ -11,3 +12,9 @@ YARD::Parser::SourceParser.register_parser_type(:puppet,
   ['pp'])
 YARD::Handlers::Processor.register_handler_namespace(:puppet,
   Puppetx::Yardoc::YARD::Handlers)
+
+# FIXME: Might not be the best idea to have the template code on the Ruby
+# LOAD_PATH as the contents of this directory really aren't library code.
+YARD::Templates::Engine.register_template_path(File.join(
+  File.dirname(__FILE__),
+  'templates'))

lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb

@@ -0,0 +1,5 @@
+include T('default/module/html')
+
+def init
+  sections :header, :box_info, :pre_docstring, T('docstring'), :children
+end

lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb

@@ -0,0 +1,9 @@
+# TODO: This should be extendable. However, the re-assignment of
+# @objects_by_letter prevents that. Submit a pull request.
+def index
+  @objects_by_letter = {}
+  objects = Registry.all(:class, :module, :hostclass).sort_by {|o| o.name.to_s }
+  objects = run_verifier(objects)
+  objects.each {|o| (@objects_by_letter[o.name.to_s[0,1].upcase] ||= []) << o }
+  erb(:index)
+end