Module: Puppet::Util::Docs

Included in:
Indirector::Indirection, Indirector::Terminus, Parameter, Provider, ProviderFeatures, ProviderFeatures::ProviderFeature, Reference
Defined in:
lib/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.

 22 23 24 25 26 27 28 29 30 31 32
 
# File 'lib/puppet/util/docs.rb', line 22 def doc extra = methods.find_all { |m| m.to_s =~ /^dochook_.+/ }.sort.filter_map { |m| send(m) }.collect { |r| "* #{r}" }.join("\n") if @doc scrub(@doc) + (extra.empty? ? '' : "\n\n#{extra}") else extra end end

#nodoc ⇒ Object (readonly)

There is nothing that would ever set this. It gets read in reference/type.rb, but will never have any value but nil.

 69 70 71
 
# File 'lib/puppet/util/docs.rb', line 69 def nodoc @nodoc end

Class Method Details

.scrub(text) ⇒ Object

Strip indentation and trailing whitespace from embedded doc fragments.

Multi-line doc fragments are sometimes indented in order to preserve the formatting of the code they’re embedded in. Since indents are syntactic elements in Markdown, we need to make sure we remove any indent that was added solely to preserve surrounding code formatting, but LEAVE any indent that delineates a Markdown element (code blocks, multi-line bulleted list items). We can do this by removing the *least common indent* from each line.

Least common indent is defined as follows:

  • Find the smallest amount of leading space on any line…

  • …excluding the first line (which may have zero indent without affecting the common indent)…

  • …and excluding lines that consist solely of whitespace.

  • The least common indent may be a zero-length string, if the fragment is not indented to match code.

  • If there are hard tabs for some dumb reason, we assume they’re at least consistent within this doc fragment.

See tests in spec/unit/util/docs_spec.rb for examples.

 117 118 119 120 121 122 123 124 125 126 127 128 129
 
# File 'lib/puppet/util/docs.rb', line 117 def scrub(text) # One-liners are easy! (One-liners may be buffered with extra newlines.)  return text.strip if text.strip !~ /\n/ excluding_first_line = text.partition("\n").last indent = excluding_first_line.scan(/^[ \t]*(?=\S)/).min || '' # prevent nil  # Clean hanging indent, if any  if indent.length > 0 text = text.gsub(/^#{indent}/, '') end # Clean trailing space  text.lines.map(&:rstrip).join("\n").rstrip end

Instance Method Details

#desc(str) ⇒ Object

Specify the actual doc string.

 6 7 8
 
# File 'lib/puppet/util/docs.rb', line 6 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.

 13 14 15 16 17
 
# File 'lib/puppet/util/docs.rb', line 13 def dochook(name, &block) method = "dochook_#{name}" meta_def method, &block end

#doctable(headers, data) ⇒ Object

Build a table

 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 65 66
 
# File 'lib/puppet/util/docs.rb', line 35 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 

 86 87 88 89 90 91 92 93 94
 
# File 'lib/puppet/util/docs.rb', line 86 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 

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

#nodoc? ⇒ Boolean

Returns:

  • (Boolean) 
 71 72 73
 
# File 'lib/puppet/util/docs.rb', line 71 def nodoc? nodoc end

#pad(value, length) ⇒ Object

Pad a field with spaces

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