From 8d9fbbd4b9d7f1d467ea6123fedcf0ee74f4e8cc Mon Sep 17 00:00:00 2001 From: Brice Figureau Date: Thu, 15 Oct 2009 20:22:46 +0200 Subject: Fix #2703 - add 'require' to puppetdoc Puppetdoc wasn't parsing 'require'. This patch adds a 'require' section to list all required class from nodes and classes. Signed-off-by: Brice Figureau --- lib/puppet/util/rdoc/code_objects.rb | 10 +++++- .../util/rdoc/generators/puppet_generator.rb | 39 ++++++++++++++++++++-- .../util/rdoc/generators/template/puppet/puppet.rb | 25 +++++++------- lib/puppet/util/rdoc/parser.rb | 14 ++++---- 4 files changed, 66 insertions(+), 22 deletions(-) diff --git a/lib/puppet/util/rdoc/code_objects.rb b/lib/puppet/util/rdoc/code_objects.rb index 6e384e1ea..056f376c6 100644 --- a/lib/puppet/util/rdoc/code_objects.rb +++ b/lib/puppet/util/rdoc/code_objects.rb @@ -88,11 +88,12 @@ module RDoc # It is mapped to a HTMLPuppetClass for display # It leverages RDoc (ruby) Class class PuppetClass < ClassModule - attr_accessor :resource_list + attr_accessor :resource_list, :requires def initialize(name, superclass) super(name,superclass) @resource_list = [] + @requires = [] end def add_resource(resource) @@ -106,6 +107,13 @@ module RDoc def superclass=(superclass) @superclass = superclass end + + # we're (ab)using the RDoc require system here. + # we're adding a required Puppet class, overriding + # the RDoc add_require method which sees ruby required files. + def add_require(required) + add_to(@requires, required) + end end # PuppetNode holds a puppet node diff --git a/lib/puppet/util/rdoc/generators/puppet_generator.rb b/lib/puppet/util/rdoc/generators/puppet_generator.rb index bf2609fd6..b7055e799 100644 --- a/lib/puppet/util/rdoc/generators/puppet_generator.rb +++ b/lib/puppet/util/rdoc/generators/puppet_generator.rb @@ -320,6 +320,26 @@ module Generators end + # This module is used to generate a referenced full name list of ContextUser + module ReferencedListBuilder + def build_referenced_list(list) + res = [] + list.each do |i| + ref = @context.find_symbol(i.name) + ref = ref.viewer if ref + name = i.respond_to?(:full_name) ? i.full_name : i.name + h_name = CGI.escapeHTML(name) + if ref and ref.document_self + path = url(ref.path) + res << { "name" => h_name, "aref" => path } + else + res << { "name" => h_name } + end + end + res + end + end + # This module is used to hold/generate a list of puppet resources # this is used in HTMLPuppetClass and HTMLPuppetNode module ResourceContainer @@ -360,7 +380,7 @@ module Generators end class HTMLPuppetClass < HtmlClass - include ResourceContainer + include ResourceContainer, ReferencedListBuilder def value_hash super @@ -376,12 +396,20 @@ module Generators secdata["resource_list"] = rdl unless rdl.empty? end end + + rl = build_require_list(@context) + @values["requires"] = rl unless rl.empty? + @values end + + def build_require_list(context) + build_referenced_list(context.requires) + end end class HTMLPuppetNode < ContextUser - include ResourceContainer + include ResourceContainer, ReferencedListBuilder attr_reader :path @@ -452,6 +480,9 @@ module Generators il = build_include_list(@context) @values["includes"] = il unless il.empty? + rl = build_require_list(@context) + @values["requires"] = rl unless rl.empty? + @values["sections"] = @context.sections.map do |section| secdata = { @@ -554,6 +585,10 @@ module Generators @values['infiles'] = files end + def build_require_list(context) + build_referenced_list(context.requires) + end + def <=>(other) self.name <=> other.name end diff --git a/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb b/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb index e12b6519c..c8f1e7d04 100644 --- a/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb +++ b/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb @@ -538,18 +538,6 @@ IF:description ENDIF:description -IF:requires -
-

Required files

- -
-START:requires - HREF:aref:name:   -END:requires -
-
-ENDIF:requires - IF:toc

Contents

@@ -601,6 +589,19 @@ END:includes
ENDIF:includes + +IF:requires +
+

Required Classes

+ +
+START:requires + HREF:aref:name: +END:requires +
+
+ENDIF:requires + START:sections
IF:sectitle diff --git a/lib/puppet/util/rdoc/parser.rb b/lib/puppet/util/rdoc/parser.rb index 554f8cb00..6d0e8f7cc 100644 --- a/lib/puppet/util/rdoc/parser.rb +++ b/lib/puppet/util/rdoc/parser.rb @@ -147,14 +147,14 @@ class Parser # create documentation for include statements we can find in +code+ # and associate it with +container+ - def scan_for_include(container, code) + def scan_for_include_or_require(container, code) code.each do |stmt| - scan_for_include(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray) + scan_for_include_or_require(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray) - if stmt.is_a?(Puppet::Parser::AST::Function) and stmt.name == "include" + if stmt.is_a?(Puppet::Parser::AST::Function) and ['include','require'].include?(stmt.name) stmt.arguments.each do |included| - Puppet.debug "found include: %s" % included.value - container.add_include(Include.new(included.value, stmt.doc)) + Puppet.debug "found #{stmt.name}: #{included.value}" + container.send("add_#{stmt.name}",Include.new(included.value, stmt.doc)) end end end @@ -220,7 +220,7 @@ class Parser code = klass.code.children if klass.code.is_a?(Puppet::Parser::AST::ASTArray) code ||= klass.code unless code.nil? - scan_for_include(cls, code) + scan_for_include_or_require(cls, code) scan_for_resource(cls, code) if Puppet.settings[:document_all] end @@ -241,7 +241,7 @@ class Parser code = node.code.children if node.code.is_a?(Puppet::Parser::AST::ASTArray) code ||= node.code unless code.nil? - scan_for_include(n, code) + scan_for_include_or_require(n, code) scan_for_vardef(n, code) scan_for_resource(n, code) if Puppet.settings[:document_all] end -- cgit