# class Puppet::Util::Reference

Manage Reference Documentation.

### Attributes

depth[RW]
doc[W]
dynamic[RW]
header[RW]
page[RW]
title[RW]

### Public Class Methods

modes() click to toggle source

    # File lib/puppet/util/reference.rb, line 19
    def self.modes
      %w{pdf text}
    end

new(name, options = {}, &block) click to toggle source

    # File lib/puppet/util/reference.rb, line 85
    def initialize(name, options = {}, &block)
      @name = name
      set_options(options)

      meta_def(:generate, &block)

      # Now handle the defaults
      @title ||= "#{@name.to_s.capitalize} Reference"
      @page ||= @title.gsub(/\s+/, '')
      @depth ||= 2
      @header ||= ""
    end

newreference(name, options = {}, &block) click to toggle source

    # File lib/puppet/util/reference.rb, line 23
    def self.newreference(name, options = {}, &block)
      ref = self.new(name, options, &block)
      instance_hash(:reference)[name.intern] = ref

      ref
    end

page(*sections) click to toggle source

    # File lib/puppet/util/reference.rb, line 30
    def self.page(*sections)
      depth = 4
      # Use the minimum depth
      sections.each do |name|
        section = reference(name) or raise "Could not find section #{name}"
        depth = section.depth if section.depth < depth
      end
    end

pdf(text) click to toggle source

    # File lib/puppet/util/reference.rb, line 39
    def self.pdf(text)
      puts "creating pdf"
      rst2latex = which('rst2latex') || which('rst2latex.py') ||
        raise("Could not find rst2latex")

      cmd = %Q{#{rst2latex} /tmp/puppetdoc.txt > /tmp/puppetdoc.tex}
      Puppet::Util.replace_file("/tmp/puppetdoc.txt") {|f| f.puts text }
      # There used to be an attempt to use secure_open / replace_file to secure
      # the target, too, but that did nothing: the race was still here.  We can
      # get exactly the same benefit from running this effort:
      File.unlink('/tmp/puppetdoc.tex') rescue nil
      output = %x{#{cmd}}
      unless $CHILD_STATUS == 0
        $stderr.puts "rst2latex failed"
        $stderr.puts output
        exit(1)
      end
      $stderr.puts output

      # Now convert to pdf
      Dir.chdir("/tmp") do
        %x{texi2pdf puppetdoc.tex >/dev/null 2>/dev/null}
      end

    end

references() click to toggle source

    # File lib/puppet/util/reference.rb, line 65
    def self.references
      instance_loader(:reference).loadall
      loaded_instances(:reference).sort { |a,b| a.to_s <=> b.to_s }
    end

### Public Instance Methods

doc() click to toggle source

    # File lib/puppet/util/reference.rb, line 73
    def doc
      if defined?(@doc)
        return "#{@name} - #{@doc}"
      else
        return @title
      end
    end

dynamic?() click to toggle source

    # File lib/puppet/util/reference.rb, line 81
    def dynamic?
      self.dynamic
    end

indent(text, tab) click to toggle source

Indent every line in the chunk except those which begin with ‘..’.

    # File lib/puppet/util/reference.rb, line 99
    def indent(text, tab)
      text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
    end

option(name, value) click to toggle source

    # File lib/puppet/util/reference.rb, line 103
    def option(name, value)
      ":#{name.to_s.capitalize}: #{value}\n"
    end

text() click to toggle source

    # File lib/puppet/util/reference.rb, line 107
    def text
      puts output
    end

to_markdown(withcontents = true) click to toggle source

    # File lib/puppet/util/reference.rb, line 111
    def to_markdown(withcontents = true)
      # First the header
      text = markdown_header(@title, 1)
      text << "\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on #{Time.now.to_s})*\n\n"

      text << @header

      text << generate

      text << self.class.footer if withcontents

      text
    end