# 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, line 55
    def PuppetGenerator.for(options)
      AllReferences::reset
      HtmlMethod::reset

      if options.all_one_file
        PuppetGeneratorInOne.new(options)
      else
        PuppetGenerator.new(options)
      end
    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, line 100
    def build_indices
      @allfiles = []
      @nodes = []
      @plugins = []

      # contains all the seen modules
      @modules = {}
      @allclasses = {}

      # remove unknown toplevels
      # it can happen that RDoc triggers a different parser for some files (ie .c, .cc or .h)
      # in this case RDoc generates a RDoc::TopLevel which we do not support in this generator
      # So let's make sure we don't generate html for those.
      @toplevels = @toplevels.select { |tl| tl.is_a? RDoc::PuppetTopLevel }

      # build the modules, classes and per modules classes and define list
      @toplevels.each do |toplevel|
        next unless toplevel.document_self
        file = HtmlFile.new(toplevel, @options, FILE_DIR)
        classes = []
        methods = []
        modules = []
        nodes = []

        # find all classes of this toplevel
        # store modules if we find one
        toplevel.each_classmodule do |k|
          generate_class_list(classes, modules, k, toplevel, CLASS_DIR)
        end

        # find all defines belonging to this toplevel
        HtmlMethod.all_methods.each do |m|
          # find parent module, check this method is not already
          # defined.
          if m.context.parent.toplevel === toplevel
            methods << m
          end
        end

        classes.each do |k|
          @allclasses[k.index_name] = k if !@allclasses.has_key?(k.index_name)
        end

        # generate nodes and plugins found
        classes.each do |k|
          if k.context.is_module?
            k.context.each_node do |name,node|
              nodes << HTMLPuppetNode.new(node, toplevel, NODE_DIR, @options)
              @nodes << nodes.last
            end
            k.context.each_plugin do |plugin|
              @plugins << HTMLPuppetPlugin.new(plugin, toplevel, PLUGIN_DIR, @options)
            end
            k.context.each_fact do |fact|
              @plugins << HTMLPuppetPlugin.new(fact, toplevel, PLUGIN_DIR, @options)
            end
          end
        end

        @files << file
        @allfiles << { "file" => file, "modules" => modules, "classes" => classes, "methods" => methods, "nodes" => nodes }
      end

      # scan all classes to create the childs references
      @allclasses.values.each do |klass|
        if superklass = klass.context.superclass
          if superklass = AllReferences[superklass] and (superklass.is_a?(HTMLPuppetClass) or superklass.is_a?(HTMLPuppetNode))
            superklass.context.add_child(klass.context)
          end
        end
      end

      @classes = @allclasses.values
    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, line 234
    def gen_class_index
      gen_an_index(@classes, 'All Classes', RDoc::Page::CLASS_INDEX, "fr_class_index.html")
      @allfiles.each do |file|
        unless file['file'].context.file_relative_name =~ /\.rb$/

          gen_composite_index(
            file,
              RDoc::Page::COMBO_INDEX,

              "#{MODULE_DIR}/fr_#{file["file"].context.module_name}.html")
        end
      end
    end

gen_composite_index(collection, template, filename) click to toggle source

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 248
    def gen_composite_index(collection, template, filename)       return if FileTest.exists?(filename)

      template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
      res1 = []
      collection['classes'].sort.each do |f|
        if f.document_self
          res1 << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.index_name) } unless f.context.is_module?
        end
      end

      res2 = []
      collection['methods'].sort.each do |f|
        res2 << { "href" => "../#{f.path}", "name" => f.index_name.sub(/\(.*\)$/,'') } if f.document_self
      end

      module_name = []
      res3 = []
      res4 = []
      collection['modules'].sort.each do |f|
        module_name << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.index_name) }
        unless f.facts.nil?
          f.facts.each do |fact|
            res3 << {"href" => "../"+CGI.escapeHTML(AllReferences["PLUGIN(#{fact.name})"].path), "name" => CGI.escapeHTML(fact.name)}
          end
        end
        unless f.plugins.nil?
          f.plugins.each do |plugin|
            res4 << {"href" => "../"+CGI.escapeHTML(AllReferences["PLUGIN(#{plugin.name})"].path), "name" => CGI.escapeHTML(plugin.name)}
          end
        end
      end

      res5 = []
      collection['nodes'].sort.each do |f|
        res5 << { "href" => "../"+CGI.escapeHTML(f.path), "name" => CGI.escapeHTML(f.name) } if f.document_self
      end

      values = {
        "module" => module_name,
        "classes"    => res1,
        'classes_title' => CGI.escapeHTML("Classes"),
        'defines_title' => CGI.escapeHTML("Defines"),
        'facts_title' => CGI.escapeHTML("Custom Facts"),
        'plugins_title' => CGI.escapeHTML("Plugins"),
        'nodes_title' => CGI.escapeHTML("Nodes"),
        'index_url'  => main_url,
        'charset'    => @options.charset,
        'style_url'  => style_url('', @options.css),
      }

      values["defines"] = res2 if res2.size>0
      values["facts"] = res3 if res3.size>0
      values["plugins"] = res4 if res4.size>0
      values["nodes"] = res5 if res5.size>0

      File.open(filename, "w") do |f|
        template.write_html_on(f, values)
      end
    end

gen_file_index() click to toggle source

generate the index of modules

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 206
    def gen_file_index
      gen_top_index(@modules.values, 'All Modules', RDoc::Page::TOP_INDEX, "fr_modules_index.html")
    end

gen_method_index() click to toggle source

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 80
    def gen_method_index
      # we don't generate an all define index
      # as the presentation is per module/per class
    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, line 195
    def gen_sub_directories
        super
        File.makedirs(MODULE_DIR)
        File.makedirs(NODE_DIR)
        File.makedirs(PLUGIN_DIR)
    rescue
        $stderr.puts $ERROR_INFO.message
        exit 1
    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, line 211
    def gen_top_index(collection, title, template, filename)
      template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
      res = []
      collection.sort.each do |f|
        if f.document_self
          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) }
        end
      end

      values = {
        "entries"    => res,
        'list_title' => CGI.escapeHTML(title),
        'index_url'  => main_url,
        'charset'    => @options.charset,
        'style_url'  => style_url('', @options.css),
      }

      File.open(filename, "w") do |f|
        template.write_html_on(f, values)
      end
    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, line 177
    def generate_class_list(classes, modules, from, html_file, class_dir)
      if from.is_module? and !@modules.has_key?(from.name)
        k = HTMLPuppetModule.new(from, html_file, class_dir, @options)
        classes << k
        @modules[from.name] = k
        modules << @modules[from.name]
      elsif from.is_module?
        modules << @modules[from.name]
      elsif !from.is_module?
        k = HTMLPuppetClass.new(from, html_file, class_dir, @options)
        classes << k
      end
      from.each_classmodule do |mod|
        generate_class_list(classes, modules, mod, html_file, class_dir)
      end
    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, line 87
    def generate_html
      super
      gen_into(@nodes)
      gen_into(@plugins)
    end

load_html_template() click to toggle source

loads our own html template file

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 72
    def load_html_template
        require 'puppet/util/rdoc/generators/template/puppet/puppet'
        extend RDoc::Page
    rescue LoadError
        $stderr.puts "Could not find Puppet template '#{template}'"
        exit 99
    end

main_url() click to toggle source

returns the initial_page url

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 310
    def main_url
      main_page = @options.main_page
      ref = nil
      if main_page
        ref = AllReferences[main_page]
        if ref
          ref = ref.path
        else
          $stderr.puts "Could not find main page #{main_page}"
        end
      end

      unless ref
        for file in @files
          if file.document_self and file.context.global
            ref = CGI.escapeHTML("#{CLASS_DIR}/#{file.context.module_name}.html")
            break
          end
        end
      end

      unless ref
        for file in @files
          if file.document_self and !file.context.global
            ref = CGI.escapeHTML("#{CLASS_DIR}/#{file.context.module_name}.html")
            break
          end
        end
      end

      unless ref
        $stderr.puts "Couldn't find anything to document"
        $stderr.puts "Perhaps you've used :stopdoc: in all classes"
        exit(1)
      end

      ref
    end

### Protected Instance Methods

initialize(options) click to toggle source

    # File lib/puppet/util/rdoc/generators/puppet_generator.rb, line 66
    def initialize(options) #:not-new:
      @options    = options
      load_html_template
    end