Proposed Module Documentation System

This page will hold the standards for how to document modules, as part of the Puppet Common Modules project. See the Module Standards page for more information.

This page is still under construction, contact Volcane on #puppet if you have any thoughts.

Overview

A previous attempt was made at proposing a standard documentation system for Puppet in the Documenting Manifests page, while there is nothing wrong with the proposal it did require substantial development on the parser to get a self generating document system like Java Doc from that, ultimately I feel the absolute best solution would be to use something like RDoc to document manifests, in the mean time I present a proposal to fill the gap.

I found a generic documentation system called Natural Docs that can parse documentation in almost any language and build page full of documentation. You can see a sample I prepared based on some of my module here.

A quick look at the format of comments that created the document in the link can be seen below:

# Module: apache
# Define: apache::vhost
# Creates a std vhost, 
#
# Parameters:
#   namevar       - the name of this resource will be the vhost name
#   aliases       - an array of aliases, or just a single alias as a string
#   prefix        - the directory to create the vhost in, defaults to /srv/www, prefixes are not auto created so be sure to first create it, it will auto depend on prefix though.
#   customlines   - not recommended, but this lets you inject custom lines into the final vhost config file, just pass an array and it will appear in order in the vhost
#   ensure        - present or absent, behaves as expected for any puppet type
#   template      - by default "apache/default-vhost.erb" gets used, you can specify your own here allow any kind of vhost to be created
#   allowoverride - if supplied an AllowOverride directive will be added to the webroot with whatever value you specify
#   options       - if supplied an Options directive will be added to the webroot with whatever you specify 
#   owner         - the user who will own the vhost webroot
#   group         - the group that will own the vhost webroot
#   
# Actions:
#   The following actions gets taken by this defined type:
#    - creates /prefix/namevar as root:root
#    - creates /prefix/namevar/html as _owner_ and _group_  
#    - creates /prefix/namevar/logs as root:root
#    - creates /etc/httpd/conf.d/namevar.conf as root:root based on _template_
#
# Requires:
#   - Package["httpd"]
#   - The directory supplied as prefix
#
# Sample Usage:
# (start code)
#         apache::vhost{"www.your.com":
#            allowoverride   => "All" ,
#            aliases         => ["your.com", "something.your.com"],
#            options         => "Indexes FollowSymLinks",
#            customlines     => "php_value include_path .:/srv/www/www.your.com/Smarty/:/usr/share/pear/",
#         }
# (end)
define apache::vhost($aliases = "NONE", $prefix = "/srv/www", $customlines = "", $ensure = "present", 
                     $template = "apache/default-vhost.erb", $allowoverride = "", $options = "", $owner="root", $group="root") {
   # body removed
}

# Class: apache::service
#
# Enables the httpd service and ensures it is running
class apache::service {
        service{"httpd":
                enable  => true,
                ensure  => running,
        }
}

For a view of what is possible with this documentation format view the walkthrough or reference at the Natural Docs site.

Due to the complexity of creating stub docs based on code alone this solution does not create placeholder documentation for classes/defines that do not have correctly formatted comments at present, to do so would require a custom parser for the puppet language and is something that will only happen once some code has been written to extend puppet. It is however very flexible and will at least make an effort to show almost any style of comments you choose above a define or class.

A possible solution could be to write a pre-processor that parses manifests and injects stub docs just before generating the final document, there exist already a need to run the manifests through a pre-processing script as you will see later in the implementation section so it would be a good place to put this stop gap solution.