From 9cd4fd14a971d0030cbb57a01963b5cbe4543e95 Mon Sep 17 00:00:00 2001 From: Charlie Sharpsteen Date: Fri, 30 May 2014 09:28:25 -0700 Subject: [PATCH] Extend doc generation to defined types Puppet Yardoc now generates documentation for defined types in addition to host classes. The actual change was fairly small, however this patch is quite large as most of the host class bits were re-architected to inherit from defined types. Host classes are basically the same as defined types with the addition of inheritance. Pops also models Host Class using a similar inheritance relationship. --- lib/puppetx/yardoc/yard/code_objects.rb | 1 + .../yard/code_objects/defined_type_object.rb | 37 +++++++++++++++++++ .../yard/code_objects/host_class_object.rb | 36 +----------------- lib/puppetx/yardoc/yard/handlers.rb | 1 + .../yard/handlers/defined_type_handler.rb | 18 +++++++++ lib/puppetx/yardoc/yard/monkey_patches.rb | 6 ++- .../html/parameter_details.erb | 0 .../default/definedtype/html/setup.rb | 1 + .../templates/default/definedtype/setup.rb | 10 +++++ .../templates/default/hostclass/html/setup.rb | 2 +- .../yard/templates/default/hostclass/setup.rb | 10 ++--- .../templates/default/layout/html/setup.rb | 2 +- 12 files changed, 80 insertions(+), 44 deletions(-) create mode 100644 lib/puppetx/yardoc/yard/code_objects/defined_type_object.rb create mode 100644 lib/puppetx/yardoc/yard/handlers/defined_type_handler.rb rename lib/puppetx/yardoc/yard/templates/default/{hostclass => definedtype}/html/parameter_details.erb (100%) create mode 100644 lib/puppetx/yardoc/yard/templates/default/definedtype/html/setup.rb create mode 100644 lib/puppetx/yardoc/yard/templates/default/definedtype/setup.rb diff --git a/lib/puppetx/yardoc/yard/code_objects.rb b/lib/puppetx/yardoc/yard/code_objects.rb index 6c70203..e9df3dd 100644 --- a/lib/puppetx/yardoc/yard/code_objects.rb +++ b/lib/puppetx/yardoc/yard/code_objects.rb @@ -1 +1,2 @@ +require_relative 'code_objects/defined_type_object' require_relative 'code_objects/host_class_object' diff --git a/lib/puppetx/yardoc/yard/code_objects/defined_type_object.rb b/lib/puppetx/yardoc/yard/code_objects/defined_type_object.rb new file mode 100644 index 0000000..c833be8 --- /dev/null +++ b/lib/puppetx/yardoc/yard/code_objects/defined_type_object.rb @@ -0,0 +1,37 @@ +require 'yard' +require 'puppet/pops' + +require_relative '../../../yardoc' + +module Puppetx::Yardoc::YARD::CodeObjects + class DefinedTypeObject < YARD::CodeObjects::NamespaceObject + # A list of parameters attached to this class. + # @return [Array] + attr_accessor :parameters + + # The `YARD::Codeobjects::Base` class pulls a bunch of shenanigans to + # insert proxy namespaces. Unfortunately, said shenanigans pick up on the + # `::` in Puppet names and start to mangle things based on rules for the + # Ruby language. + # + # Therefore, we must override `new` for great justice. + # + # TODO: Ask around on the YARD mailing list to see if there is a way around + # this ugliness. + # + # Alternately, consider ensuring all `proxy` objects resolve to a + # placeholder `NamespaceObject` as the name mangling behavior of these is + # easier to control. + def self.new(namespace, name, *args, &block) + # Standard Ruby boilerplate for `new` + obj = self.allocate + obj.send :initialize, namespace, name, *args + + # The last bit of `YARD::CodeObjects::Base.new`. + existing_obj = YARD::Registry.at(obj.path) + obj = existing_obj if existing_obj && existing_obj.class == self + yield(obj) if block_given? + obj + end + end +end diff --git a/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb b/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb index bb85b67..d8b138f 100644 --- a/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb +++ b/lib/puppetx/yardoc/yard/code_objects/host_class_object.rb @@ -1,43 +1,11 @@ -require 'yard' -require 'puppet/pops' - -require_relative '../../../yardoc' +require_relative 'defined_type_object' module Puppetx::Yardoc::YARD::CodeObjects - class HostClassObject < YARD::CodeObjects::NamespaceObject + class HostClassObject < DefinedTypeObject # The {HostClassObject} that this class inherits from, if any. # @return [HostClassObject, Proxy, nil] attr_accessor :parent_class - # A list of parameters attached to this class. - # @return [Array] - attr_accessor :parameters - - # The `YARD::Codeobjects::Base` class pulls a bunch of shenanigans to - # insert proxy namespaces. Unfortunately, said shenanigans pick up on the - # `::` in Puppet names and start to mangle things based on rules for the - # Ruby language. - # - # Therefore, we must override `new` for great justice. - # - # TODO: Ask around on the YARD mailing list to see if there is a way around - # this ugliness. - # - # Alternately, consider ensuring all `proxy` objects resolve to a - # placeholder `NamespaceObject` as the name mangling behavior of these is - # easier to control. - def self.new(namespace, name, *args, &block) - # Standard Ruby boilerplate for `new` - obj = self.allocate - obj.send :initialize, namespace, name, *args - - # The last bit of `YARD::CodeObjects::Base.new`. - existing_obj = YARD::Registry.at(obj.path) - obj = existing_obj if existing_obj && existing_obj.class == self - yield(obj) if block_given? - obj - end - # NOTE: `include_mods` is never used as it makes no sense for Puppet, but # this is called by `YARD::Registry` and it will pass a parameter. def inheritance_tree(include_mods = false) diff --git a/lib/puppetx/yardoc/yard/handlers.rb b/lib/puppetx/yardoc/yard/handlers.rb index 085dc55..fe3737c 100644 --- a/lib/puppetx/yardoc/yard/handlers.rb +++ b/lib/puppetx/yardoc/yard/handlers.rb @@ -1,2 +1,3 @@ require_relative 'handlers/base' +require_relative 'handlers/defined_type_handler' require_relative 'handlers/host_class_handler' diff --git a/lib/puppetx/yardoc/yard/handlers/defined_type_handler.rb b/lib/puppetx/yardoc/yard/handlers/defined_type_handler.rb new file mode 100644 index 0000000..e21f67d --- /dev/null +++ b/lib/puppetx/yardoc/yard/handlers/defined_type_handler.rb @@ -0,0 +1,18 @@ +require_relative 'base' + +module Puppetx::Yardoc::YARD::Handlers + class DefinedTypeHandler < Base + handles ResourceTypeDefinition + + process do + obj = DefinedTypeObject.new(:root, statement.pops_obj.name) do |o| + o.parameters = statement.parameters.map do |a| + param_tuple = [a[0].pops_obj.name] + param_tuple << ( a[1].nil? ? nil : a[1].source ) + end + end + + register obj + end + end +end diff --git a/lib/puppetx/yardoc/yard/monkey_patches.rb b/lib/puppetx/yardoc/yard/monkey_patches.rb index b7b1845..9b8f75c 100644 --- a/lib/puppetx/yardoc/yard/monkey_patches.rb +++ b/lib/puppetx/yardoc/yard/monkey_patches.rb @@ -6,7 +6,7 @@ require 'yard' class YARD::CLI::Yardoc def all_objects - YARD::Registry.all(:root, :module, :class, :hostclass) + YARD::Registry.all(:root, :module, :class, :hostclass, :definedtype) end end @@ -14,4 +14,8 @@ class YARD::CLI::Stats def stats_for_hostclasses output 'Puppet Classes', *type_statistics(:hostclass) end + + def stats_for_definedtypes + output 'Puppet Types', *type_statistics(:definedtype) + end end diff --git a/lib/puppetx/yardoc/yard/templates/default/hostclass/html/parameter_details.erb b/lib/puppetx/yardoc/yard/templates/default/definedtype/html/parameter_details.erb similarity index 100% rename from lib/puppetx/yardoc/yard/templates/default/hostclass/html/parameter_details.erb rename to lib/puppetx/yardoc/yard/templates/default/definedtype/html/parameter_details.erb diff --git a/lib/puppetx/yardoc/yard/templates/default/definedtype/html/setup.rb b/lib/puppetx/yardoc/yard/templates/default/definedtype/html/setup.rb new file mode 100644 index 0000000..91e114a --- /dev/null +++ b/lib/puppetx/yardoc/yard/templates/default/definedtype/html/setup.rb @@ -0,0 +1 @@ +include T('default/module/html') diff --git a/lib/puppetx/yardoc/yard/templates/default/definedtype/setup.rb b/lib/puppetx/yardoc/yard/templates/default/definedtype/setup.rb new file mode 100644 index 0000000..5d7e4d1 --- /dev/null +++ b/lib/puppetx/yardoc/yard/templates/default/definedtype/setup.rb @@ -0,0 +1,10 @@ +include T('default/module') + +def init + sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details +end + +def parameter_details + return if object.parameters.empty? + erb(:parameter_details) +end diff --git a/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb b/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb index 91e114a..3cb9cdf 100644 --- a/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb +++ b/lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb @@ -1 +1 @@ -include T('default/module/html') +include T('default/definedtype/html') diff --git a/lib/puppetx/yardoc/yard/templates/default/hostclass/setup.rb b/lib/puppetx/yardoc/yard/templates/default/hostclass/setup.rb index 959a4f3..081d237 100644 --- a/lib/puppetx/yardoc/yard/templates/default/hostclass/setup.rb +++ b/lib/puppetx/yardoc/yard/templates/default/hostclass/setup.rb @@ -1,12 +1,8 @@ -include T('default/module') +include T('default/definedtype') def init - sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details, :subclasses -end - -def parameter_details - return if object.parameters.empty? - erb(:parameter_details) + super + sections.push :subclasses end def subclasses diff --git a/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb b/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb index 68d3960..a53bfbd 100644 --- a/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb +++ b/lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb @@ -2,7 +2,7 @@ # @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 = Registry.all(:class, :module, :hostclass, :definedtype).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)