Module: Puppet::Util::Docs

Included in:
Indirector::Indirection, Indirector::Terminus, Network::Handler, Parameter, Parser::AST, Provider, ProviderFeatures, ProviderFeatures::ProviderFeature, Reference
Defined in:
lib/vendor/puppet/util/docs.rb

Overview

Some simple methods for helping manage automatic documentation generation.

Constant Summary collapse

HEADER_LEVELS = 
[nil, "#", "##", "###", "####", "#####"]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#doc ⇒ Object

Generate the full doc string.



20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/vendor/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

#nodoc ⇒ Object (readonly)

Returns the value of attribute nodoc.



66
67
68
 
# File 'lib/vendor/puppet/util/docs.rb', line 66

def nodoc
  @nodoc
end

Class Method Details

.scrub(text) ⇒ Object

Handle the inline indentation in the docs.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/vendor/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
      puts detail.backtrace
      puts detail
    end
  else
    return text
  end

end

Instance Method Details

#desc(str) ⇒ Object

Specify the actual doc string.



4
5
6
 
# File 'lib/vendor/puppet/util/docs.rb', line 4

def desc(str)
  @doc = str
end

#dochook(name, &block) ⇒ Object

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.



11
12
13
14
15
 
# File 'lib/vendor/puppet/util/docs.rb', line 11

def dochook(name, &block)
  method = "dochook_#{name}"

  meta_def method, &block
end

#doctable(headers, data) ⇒ Object

Build a table



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/vendor/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) ⇒ Object 



82
83
84
85
86
87
88
89
90
 
# File 'lib/vendor/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) ⇒ Object 



78
79
80
 
# File 'lib/vendor/puppet/util/docs.rb', line 78

def markdown_header(name, level)
  "#{HEADER_LEVELS[level]} #{name}\n\n"
end

#nodoc? ⇒ Boolean

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/vendor/puppet/util/docs.rb', line 67

def nodoc?
  nodoc
end

#pad(value, length) ⇒ Object

Pad a field with spaces



72
73
74
 
# File 'lib/vendor/puppet/util/docs.rb', line 72

def pad(value, length)
  value.to_s + (" " * (length - value.to_s.length))
end