# module Puppet::Util::Docs

Some simple methods for helping manage automatic documentation generation.

### Constants

HEADER_LEVELS

### Attributes

doc[W]
nodoc[R]

### Public Class Methods

scrub(text) click to toggle source

Handle the inline indentation in the docs.

    # File lib/puppet/util/docs.rb, line 93
    def scrub(text)
      # Stupid markdown
      #text = text.gsub("<%=", "&lt;%=")
      # For text with no carriage returns, there's nothing to do.
      return text if text !~ /\n/
      indent = nil

      # If we can match an indentation, then just remove that same level of
      # indent from every line.  However, ignore any indentation on the
      # first line, since that can be inconsistent.
      text = text.lstrip
      text.gsub!(/^([\t]+)/) { |s| " "*8*s.length; } # Expand leading tabs
      # Find first non-empty line after the first line:
      line2start = (text =~ /(\n?\s*\n)/)
      line2start += $1.length
      if (text[line2start..-1] =~ /^([ ]+)\S/) == 0
        indent = Regexp.quote($1)
        begin
          return text.gsub(/^#{indent}/,'')
        rescue => detail
          Puppet.log_exception(detail)
        end
      else
        return text
      end

    end

### Public Instance Methods

desc(str) click to toggle source

Specify the actual doc string.

    # File lib/puppet/util/docs.rb, line 4
    def desc(str)
      @doc = str
    end

doc() click to toggle source

Generate the full doc string.

    # File lib/puppet/util/docs.rb, line 20
    def doc
      extra = methods.find_all { |m| m.to_s =~ /^dochook_.+/ }.sort.collect { |m|
        self.send(m)
      }.delete_if {|r| r.nil? }.join("  ")

      if @doc
        @doc + (extra.empty? ? '' : "\n\n" + extra)
      else
        extra
      end
    end

dochook(name, &block) click to toggle source

Add a new autodoc block. We have to define these as class methods, rather than just sticking them in a hash, because otherwise they’re too difficult to do inheritance with.

    # File lib/puppet/util/docs.rb, line 11
    def dochook(name, &block)
      method = "dochook_#{name}"

      meta_def method, &block
    end

doctable(headers, data) click to toggle source

Build a table

    # File lib/puppet/util/docs.rb, line 33
    def doctable(headers, data)
      str = "\n\n"

      lengths = []
      # Figure out the longest field for all columns
      data.each do |name, values|
        [name, values].flatten.each_with_index do |value, i|
          lengths[i] ||= 0
          lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
        end
      end

      # The headers could also be longest
      headers.each_with_index do |value, i|
        lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
      end

      # Add the header names
      str += headers.zip(lengths).collect { |value, num| pad(value, num) }.join(" | ") + " |" + "\n"

      # And the header row
      str += lengths.collect { |num| "-" * num }.join(" | ") + " |" + "\n"

      # Now each data row
      data.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |name, rows|
        str += [name, rows].flatten.zip(lengths).collect do |value, length|
          pad(value, length)
        end.join(" | ") + " |" + "\n"
      end

      str + "\n"
    end

markdown_definitionlist(term, definition) click to toggle source

    # File lib/puppet/util/docs.rb, line 82
    def markdown_definitionlist(term, definition)
      lines = scrub(definition).split("\n")
      str = "#{term}\n: #{lines.shift}\n"
      lines.each do |line|
        str << "  " if line =~ /\S/
        str << "#{line}\n"
      end
      str << "\n"
    end

markdown_header(name, level) click to toggle source

    # File lib/puppet/util/docs.rb, line 78
    def markdown_header(name, level)
      "#{HEADER_LEVELS[level]} #{name}\n\n"
    end

nodoc?() click to toggle source

    # File lib/puppet/util/docs.rb, line 67
    def nodoc?
      nodoc
    end

pad(value, length) click to toggle source

Pad a field with spaces

    # File lib/puppet/util/docs.rb, line 72
    def pad(value, length)
      value.to_s + (" " * (length - value.to_s.length))
    end