Puppet class browser¶

There are links labeled "Documentation" on the settings/puppet classes page, which will direct your browser to the html documentation for a particular puppet module.

The documentation is generated by a rake task that uses the puppetdoc utility and may need some customization to work at a particular site.

Configuration¶

Document root¶

Ensure that there is an entry in the config/settings.yaml for the document root

:document_root: /var/www

The documentation will be written into document_root/puppet/rdoc and this location must be in an area that is served by your web server. Any location that is served by apache or webrick/mongrel will do, so foreman's public directory is also a suitable candidate.

manifest cleanup¶

The puppetdoc utility is sensitive to the layout of the manifests and modules directories. In particular, it cannot handle circular or broken symlinks. If you have problems running puppetdoc then move extras/rdoc/rdoc_prepare_script.rb to scripts/rdoc_prepare_script.rb and then edit it to suit your site. Most sites will not require a scripts/rdoc_prepare_script.rb file.

Generating the documentation.¶

Simple case¶

This is performed by running

rake puppet:rdoc:generate

Complex case¶

When the puppetdoc utility fails to process your manifests then you will have to sanitize your puppet modules directory. The rake puppet:rdoc:generate task will check for the existence of scripts/rdoc_prepare_script.rb, and runs this before the the puppetdoc command is executed. This script is expected to copy the source files for your modules to another location, fix any issues and then terminate, passing back the location of the copied directory tree.

A fairly complex example is provided in extras/rdoc/rdoc_prepare_script.rb.

The final command to generate the documentation is then the same as for the simple case

rake puppet:rdoc:generate