class Generators::PuppetGenerator

This is a specialized HTMLGenerator tailored to Puppet manifests

Public Class Methods

for(options) click to toggle source
   # File lib/puppet/util/rdoc/generators/puppet_generator.rb
55 def PuppetGenerator.for(options)
56   AllReferences::reset
57   HtmlMethod::reset
58 
59   if options.all_one_file
60     PuppetGeneratorInOne.new(options)
61   else
62     PuppetGenerator.new(options)
63   end
64 end

Public Instance Methods

build_indices() click to toggle source

Generate:

the list of modules
the list of classes and definitions of a specific module
the list of all classes
the list of nodes
the list of resources
    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
100 def build_indices
101   @allfiles = []
102   @nodes = []
103   @plugins = []
104 
105   # contains all the seen modules
106   @modules = {}
107   @allclasses = {}
108 
109   # remove unknown toplevels
110   # it can happen that RDoc triggers a different parser for some files (ie .c, .cc or .h)
111   # in this case RDoc generates a RDoc::TopLevel which we do not support in this generator
112   # So let's make sure we don't generate html for those.
113   @toplevels = @toplevels.select { |tl| tl.is_a? RDoc::PuppetTopLevel }
114 
115   # build the modules, classes and per modules classes and define list
116   @toplevels.each do |toplevel|
117     next unless toplevel.document_self
118     file = HtmlFile.new(toplevel, @options, FILE_DIR)
119     classes = []
120     methods = []
121     modules = []
122     nodes = []
123 
124     # find all classes of this toplevel
125     # store modules if we find one
126     toplevel.each_classmodule do |k|
127       generate_class_list(classes, modules, k, toplevel, CLASS_DIR)
128     end
129 
130     # find all defines belonging to this toplevel
131     HtmlMethod.all_methods.each do |m|
132       # find parent module, check this method is not already
133       # defined.
134       if m.context.parent.toplevel === toplevel
135         methods << m
136       end
137     end
138 
139     classes.each do |k|
140       @allclasses[k.index_name] = k if !@allclasses.has_key?(k.index_name)
141     end
142 
143     # generate nodes and plugins found
144     classes.each do |k|
145       if k.context.is_module?
146         k.context.each_node do |name,node|
147           nodes << HTMLPuppetNode.new(node, toplevel, NODE_DIR, @options)
148           @nodes << nodes.last
149         end
150         k.context.each_plugin do |plugin|
151           @plugins << HTMLPuppetPlugin.new(plugin, toplevel, PLUGIN_DIR, @options)
152         end
153         k.context.each_fact do |fact|
154           @plugins << HTMLPuppetPlugin.new(fact, toplevel, PLUGIN_DIR, @options)
155         end
156       end
157     end
158 
159     @files << file
160     @allfiles << { "file" => file, "modules" => modules, "classes" => classes, "methods" => methods, "nodes" => nodes }
161   end
162 
163   # scan all classes to create the child's references
164   @allclasses.values.each do |klass|
165     superklass = klass.context.superclass
166     if superklass
167       superklass = AllReferences[superklass]
168       if superklass && (superklass.is_a?(HTMLPuppetClass) || superklass.is_a?(HTMLPuppetNode))
169         superklass.context.add_child(klass.context)
170       end
171     end
172   end
173 
174   @classes = @allclasses.values
175 end
gen_class_index() click to toggle source

generate the all classes index file and the combo index

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
236 def gen_class_index
237   gen_an_index(@classes, 'All Classes', RDoc::Page::CLASS_INDEX, "fr_class_index.html")
238   @allfiles.each do |file|
239     unless file['file'].context.file_relative_name =~ /\.rb$/
240 
241       gen_composite_index(
242         file,
243           RDoc::Page::COMBO_INDEX,
244 
245           "#{MODULE_DIR}/fr_#{file["file"].context.module_name}.html")
246     end
247   end
248 end
gen_composite_index(collection, template, filename) click to toggle source
    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
250 def gen_composite_index(collection, template, filename)
251   return if Puppet::FileSystem.exist?(filename)
252 
253   template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
254   res1 = []
255   collection['classes'].sort.each do |f|
256     if f.document_self
257       res1 << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.index_name) } unless f.context.is_module?
258     end
259   end
260 
261   res2 = []
262   collection['methods'].sort.each do |f|
263     res2 << { "href" => "../#{f.path}", "name" => f.index_name.sub(/\(.*\)$/,'') } if f.document_self
264   end
265 
266   module_name = []
267   res3 = []
268   res4 = []
269   collection['modules'].sort.each do |f|
270     module_name << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.index_name) }
271     unless f.facts.nil?
272       f.facts.each do |fact|
273         res3 << {"href" => "../"+CGI.escapeHTML(AllReferences["PLUGIN(#{fact.name})"].path), "name" => CGI.escapeHTML(fact.name)}
274       end
275     end
276     unless f.plugins.nil?
277       f.plugins.each do |plugin|
278         res4 << {"href" => "../"+CGI.escapeHTML(AllReferences["PLUGIN(#{plugin.name})"].path), "name" => CGI.escapeHTML(plugin.name)}
279       end
280     end
281   end
282 
283   res5 = []
284   collection['nodes'].sort.each do |f|
285     res5 << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.name) } if f.document_self
286   end
287 
288   values = {
289     "module" => module_name,
290     "classes"    => res1,
291     'classes_title' => CGI.escapeHTML("Classes"),
292     'defines_title' => CGI.escapeHTML("Defines"),
293     'facts_title' => CGI.escapeHTML("Custom Facts"),
294     'plugins_title' => CGI.escapeHTML("Plugins"),
295     'nodes_title' => CGI.escapeHTML("Nodes"),
296     'index_url'  => main_url,
297     'charset'    => @options.charset,
298     'style_url'  => style_url('', @options.css),
299   }
300 
301   values["defines"] = res2 if res2.size>0
302   values["facts"] = res3 if res3.size>0
303   values["plugins"] = res4 if res4.size>0
304   values["nodes"] = res5 if res5.size>0
305 
306   Puppet::FileSystem.open(filename, nil, "w:UTF-8") do |f|
307     template.write_html_on(f, values)
308   end
309 end
gen_file_index() click to toggle source

generate the index of modules

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
208 def gen_file_index
209   gen_top_index(@modules.values, 'All Modules', RDoc::Page::TOP_INDEX, "fr_modules_index.html")
210 end
gen_method_index() click to toggle source
   # File lib/puppet/util/rdoc/generators/puppet_generator.rb
80 def gen_method_index
81   # we don't generate an all define index
82   # as the presentation is per module/per class
83 end
gen_sub_directories() click to toggle source

generate all the subdirectories, modules, classes and files

Calls superclass method
    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
197 def gen_sub_directories
198     super
199     File.makedirs(MODULE_DIR)
200     File.makedirs(NODE_DIR)
201     File.makedirs(PLUGIN_DIR)
202 rescue
203     $stderr.puts $ERROR_INFO.message
204     exit 1
205 end
gen_top_index(collection, title, template, filename) click to toggle source

generate a top index

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
213 def gen_top_index(collection, title, template, filename)
214   template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
215   res = []
216   collection.sort.each do |f|
217     if f.document_self
218       res << { "classlist" => CGI.escapeHTML("#{MODULE_DIR}/fr_#{f.index_name}.html"), "module" => CGI.escapeHTML("#{CLASS_DIR}/#{f.index_name}.html"),"name" => CGI.escapeHTML(f.index_name) }
219     end
220   end
221 
222   values = {
223     "entries"    => res,
224     'list_title' => CGI.escapeHTML(title),
225     'index_url'  => main_url,
226     'charset'    => @options.charset,
227     'style_url'  => style_url('', @options.css),
228   }
229 
230   Puppet::FileSystem.open(filename, nil, "w:UTF-8") do |f|
231     template.write_html_on(f, values)
232   end
233 end
generate_class_list(classes, modules, from, html_file, class_dir) click to toggle source

produce a class/module list of HTMLPuppetModule/HTMLPuppetClass based on the code object traversal.

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
179 def generate_class_list(classes, modules, from, html_file, class_dir)
180   if from.is_module? and !@modules.has_key?(from.name)
181     k = HTMLPuppetModule.new(from, html_file, class_dir, @options)
182     classes << k
183     @modules[from.name] = k
184     modules << @modules[from.name]
185   elsif from.is_module?
186     modules << @modules[from.name]
187   elsif !from.is_module?
188     k = HTMLPuppetClass.new(from, html_file, class_dir, @options)
189     classes << k
190   end
191   from.each_classmodule do |mod|
192     generate_class_list(classes, modules, mod, html_file, class_dir)
193   end
194 end
generate_html() click to toggle source

This is the central method, it generates the whole structures along with all the indices.

Calls superclass method
   # File lib/puppet/util/rdoc/generators/puppet_generator.rb
87 def generate_html
88   super
89   gen_into(@nodes)
90   gen_into(@plugins)
91 end
load_html_template() click to toggle source

loads our own html template file

   # File lib/puppet/util/rdoc/generators/puppet_generator.rb
72 def load_html_template
73     require_relative '../../../../puppet/util/rdoc/generators/template/puppet/puppet'
74     extend RDoc::Page
75 rescue LoadError
76     $stderr.puts "Could not find Puppet template '#{template}'"
77     exit 99
78 end
main_url() click to toggle source

returns the initial_page url

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb
312 def main_url
313   main_page = @options.main_page
314   ref = nil
315   if main_page
316     ref = AllReferences[main_page]
317     if ref
318       ref = ref.path
319     else
320       $stderr.puts "Could not find main page #{main_page}"
321     end
322   end
323 
324   unless ref
325     for file in @files
326       if file.document_self and file.context.global
327         ref = CGI.escapeHTML("#{CLASS_DIR}/#{file.context.module_name}.html")
328         break
329       end
330     end
331   end
332 
333   unless ref
334     for file in @files
335       if file.document_self and !file.context.global
336         ref = CGI.escapeHTML("#{CLASS_DIR}/#{file.context.module_name}.html")
337         break
338       end
339     end
340   end
341 
342   unless ref
343     $stderr.puts "Couldn't find anything to document"
344     $stderr.puts "Perhaps you've used :stopdoc: in all classes"
345     exit(1)
346   end
347 
348   ref
349 end

Protected Instance Methods

initialize(options) click to toggle source
   # File lib/puppet/util/rdoc/generators/puppet_generator.rb
66 def initialize(options) #:not-new:
67   @options    = options
68   load_html_template
69 end