Puppet Manifest Documentation¶
Starting with version 0.24.7, Puppet ships with an enhanced puppet doc executable that allows user to generate browser readable HTML or direct to console output of documentation embedded in Puppet manifests.
Direct to Console Output¶
The first mode for puppet doc is to output the documentation contained in the the various comments of a sole manifest without any post-processing to the console.
This mode of running puppet doc is perfect if you want to post process the documentation by another system to produce man pages from ReST (for instance with Pandoc: http://johnmacfarlane.net/pandoc/)
$ puppet doc [-all] <file-spec>
<file-spec>: path to a manifest file, for instance /etc/puppet/manifests/site.pp
By default, it outputs documentation from nodes, classes and definitions contained into the manifest given as argument.
--all or -a: produces also documentation attached to resources.
RDoc HTML Generation¶
The second mode of puppet doc is to generate a set of HTML files, as RDoc does for ruby or Javadoc for Java.
The system is based on RDoc, and as such uses [RDoc markup][rdoc].
$ puppet doc [--all] --mode rdoc [--outputdir <path-spec>] [--debug|--verbose] [--trace] [--modulepath <path-list>] [--manifestdir <path-spec>] [--config <file-spec>]
—all produces documentation for all the resources along with the other documentations produced. —outputdir store the result into the given directory instead of ‘doc’ in the current directory. —debug display debug and greater level messages —verbose display info and greater level messages —trace display Ruby stack trace in case of error —modulepath override the puppet.conf modulepath. See puppetmasterd modulepath option. —manifestdir override the puppet.conf manifestdir. See puppetmasterd manifestdir option. —config override the default puppet.conf location. See puppetmasterd config option. The puppetdoc binary in RDoc mode supports most of the puppetmasterd options related to module or manifest location, including environments.
If no —config or —configdir options are used, then puppet doc uses the default Puppet configuration file for the current user (usually \~/.puppet or /etc/puppet/).
If one puppet.conf file can be found in —configdir or —config, then the modulepath and manifestdir of the [master] section are used.
Passing the —modulepath or the —manifestdir options on command line overrides their respective values found in the puppet.conf file.
By default, puppet doc generates documentation with comments associated with classes, nodes, definitions, nodes global variables, custom facts and Puppet plugins located in modules.
Documentation is produced for each class and definition in each module. Global manifests (i.e. those under manifestdir) are located under the special “<site>” module. Each class, module or plugin is cross-referenced throughout the whole documentation.
Module documentation is extracted from an existing README file that would be located under the module root directory:
When producing the documentation for the whole module, the README file will be used.
Class documentation is extracted as in direct to console output from the comments just before the said class. The same for nodes, definitions, global assignments, or resources.
The system reports included classes in including class.
Puppet doc Output¶
The Puppet Manifest Documentation system is based upon RDoc. By default, puppet doc outputs the documentation under the doc directory (which can be overridden with —outputdir). This directory can be viewed by a web browser or can be directly put under a document root of a Web server for global access.
The system outputs one file per module, several files per classes, along with global indices and per modules indices.
Since the HTML generation is based on RDoc, the various comments where the documentation is extracted should be formatted with RDoc markup. The RDoc markup is lightweight, implicit and non-intrusive.
Here are the more important RDoc Markup rules extracted from RDoc documentation.
Note that most of these markup elements are recognized only if they are non-indented and start at the beginning of line.
Lists are typed as paragraphs with:
- a ‘*’ or ‘–’ (for bullet lists)
- a digit followed by a period for numbered lists
Labelled lists (sometimes called description lists) are typed using square brackets for the label.
- [cat] small domestic animal
- [+cat+] command to copy standard input
Labelled lists may also be produced by putting a double colon after the label. This sets the result in tabular form, so the descriptions all line up.
- cat:: small domestic animal
- +cat+:: command to copy standard input
For both kinds of labelled lists, if the body text starts on the same line as the label, then the start of that text determines the block indent for the rest of the body. The text may also start on the line following the label, indented from the start of the label. This is often preferable if the label is long.
Headings are entered using equals signs
- = Level One Heading
- == Level Two Heading
- and so on
Rules (horizontal lines) are entered using three or more hyphens.
Non-verbatim text can be marked up
Hyperlinks to the web starting http:, mailto:, ftp:, or www. are recognized. An HTTP url that references an external image file is converted into an inline <IMG..>. Hyperlinks starting link: are assumed to refer to local files whose path is relative to the —outputdir directory.
Hyperlinks can also be of the form label[url], in which case the label is used in the displayed text, and url is used as the target.
Puppetdoc stops processing comments if it finds a comment line containing #—. This can be used to separate external from internal comments, or to stop a comment being associated with a method, class, or module. Commenting can be turned back on with a line that starts #++.
Comment blocks can contain other directives
:include:filename : include the contents of the named file at this point. The file will be searched for in the current directory by default. The contents of the file will be shifted to have the same indentation as the ‘:’ at the start of the :include: directive.
:title:text : Sets the title for the document.
:main:name : Sets name as the main page.