From e3d2602cba951bd31eaa757db5fc64a9a4cd848b Mon Sep 17 00:00:00 2001 From: Charlie Sharpsteen Date: Sun, 25 May 2014 22:59:46 -0700 Subject: [PATCH] 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 | 1 + .../yard/code_objects/host_class_object.rb | 10 ++++++++++ lib/puppetx/yardoc/yard/handlers/base.rb | 6 +++++- .../yardoc/yard/handlers/host_class_handler.rb | 2 +- lib/puppetx/yardoc/yard/monkey_patches.rb | 17 +++++++++++++++++ lib/puppetx/yardoc/yard/plugin.rb | 7 +++++++ .../templates/default/hostclass/html/setup.rb | 5 +++++ .../yard/templates/default/layout/html/setup.rb | 9 +++++++++ 8 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 lib/puppetx/yardoc/yard/code_objects.rb create mode 100644 lib/puppetx/yardoc/yard/code_objects/host_class_object.rb create mode 100644 lib/puppetx/yardoc/yard/monkey_patches.rb create mode 100644 lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb create mode 100644 lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb diff --git a/lib/puppetx/yardoc/yard/code_objects.rb b/lib/puppetx/yardoc/yard/code_objects.rb new file mode 100644 index 0000000..6c70203 --- /dev/null +++ b/lib/puppetx/yardoc/yard/code_objects.rb @@ -0,0 +1 @@ +require_relative 'code_objects/host_class_object' diff --git a/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb b/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb new file mode 100644 index 0000000..0927d91 --- /dev/null +++ b/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 diff --git a/lib/puppetx/yardoc/yard/handlers/base.rb b/lib/puppetx/yardoc/yard/handlers/base.rb index 552532f..0e50359 100644 --- a/lib/puppetx/yardoc/yard/handlers/base.rb +++ b/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} diff --git a/lib/puppetx/yardoc/yard/handlers/host_class_handler.rb b/lib/puppetx/yardoc/yard/handlers/host_class_handler.rb index 6db7856..5c32916 100644 --- a/lib/puppetx/yardoc/yard/handlers/host_class_handler.rb +++ b/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 diff --git a/lib/puppetx/yardoc/yard/monkey_patches.rb b/lib/puppetx/yardoc/yard/monkey_patches.rb new file mode 100644 index 0000000..b7b1845 --- /dev/null +++ b/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 diff --git a/lib/puppetx/yardoc/yard/plugin.rb b/lib/puppetx/yardoc/yard/plugin.rb index 4cc4e7d..e05ace0 100644 --- a/lib/puppetx/yardoc/yard/plugin.rb +++ b/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')) diff --git a/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb b/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb new file mode 100644 index 0000000..1e51893 --- /dev/null +++ b/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 diff --git a/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb b/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb new file mode 100644 index 0000000..68d3960 --- /dev/null +++ b/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