Puppet

# Puppet Manifest Documentation

Starting with version 0.24.7, Puppet ships with an enhanced

puppetdoc executable that allows user to generate browser readable

HTML or direct to console output of documentation embedded in

Puppet manifests.

# Documentation format

[rdoc]: http://links.puppetlabs.com/rdoc_markup

Documentation for a class (or defined type) should be written in

[RDoc format][rdoc] and placed in a large comment directly before the class

being documented. For example:

    # = Class: users

    #

    # This class installs our default set of users in our servers.

    #

    # == Parameters:

    #

    # $starting_uid::   This global variable is used to set the minimum

    #                   uid used for our users.

    #

    # $primary_group::  The primary group for all of our default users.

    #

    # == Actions:

    #   Install the default set of users: [dana,fox]

    #

    # == Requires:

    #   - Package["zsh"]

    #

    # == Sample Usage:

    # 

    #   class {'users':

    #     starting_uid  => 501,

    #     primary_group => 'staff',

    #   }

    #

    class users {

                  ...

    }

Note: the next line after the documentation must be the class that

is being documented as in the example above.

# Direct to Console Output

The first mode for puppetdoc 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 puppetdoc 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/](http://johnmacfarlane.net/pandoc/))

Usage:

    $ puppetdoc [-all] <file-spec>

Argument:

    <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.

Option:

    --all or -a: produces also documentation attached to resources.

# RDoc HTML Generation

The second mode of puppetdoc 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].

Usage:

    $ puppetdoc [--all] --mode rdoc [--outputdir <path-spec>] [--debug|--verbose] [--trace]

                [--modulepath <path-list>] [--manifestdir <path-spec>] [--config <file-spec>]

Options:

--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 puppetdoc uses

the default puppetmasterd 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 [puppetmasterd] 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, puppetdoc 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:

    /etc/puppet/modules/postfix/manifest/init.pp

    /etc/puppet/modules/postfix/README

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.

# Puppetdoc Output

The Puppet Manifest Documentation system is based upon RDoc. By

default, puppetdoc 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.

# RDoc markup

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

    -   \*bold\*

    -   \_italic\_

    -   +typewriter+

-   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.