Getting Started with Puppet Strings

Puppet Labs recently released Puppet Strings which is a Puppet Face that is a proposed replacement for the puppet doc command. The Puppet Strings face uses YARD and the Puppet Parser to generate HTML documentation about Puppet manifests and Puppet extensions written in Ruby. I thought I’d try it on the module that I maintain for Sensu.

Installation

Puppet Strings is pretty easy to install. It’s under regular development though so you should be sure to keep it up to date.

Prerequisites

The installation has a few prerequisites. You will need:

• Ruby 1.9.3 or newer installed.
• Puppet 3.7 or newer installed.

And the yard Ruby Gem.

1

$ sudo gem install yard

Installing Puppet Strings

You can install Puppet Strings using the puppet module command:

1

$ puppet module install puppetlabs-strings

Or by cloning the Git repository into the Puppet module path, for example:

1
2

$ cd ~/.puppet/modules/
$ git clone https://github.com/puppetlabs/puppetlabs-strings.git strings

Building module documentation

As Puppet Strings is a Puppet Face it is available as a sub-command of the puppet binary. To use it change into the directory of your Puppet module and run puppet strings.

1
2

$ cd sensu-puppet
$ puppet strings

Puppet Strings will process the contents of your README.md¹, all the *.pp files in your manifests directory, and all the *.rb files in your lib directory. It will use Yard to produce HTML (and CSS/JS for styling and presentation) that documents your classes, defined types and your types and providers. Yard is fairly configurable and you can tweak the options you want to pass to it by specifying them in a .yardopts file in the root of your module directory.

Displaying our documentation

Puppet Strings comes with a built-in web server that can display our generated documentation. You can run it like this:

1

$ puppet strings server

You can also easily add your documentation to GitHub as a Pages site as we’ve done here with the Sensu Puppet module.

Summary

Puppet Strings isn’t quite feature complete yet and it is not quite a total replacement for puppet doc but it’s headed in the right direction. With some simple scripting you could easily use Puppet Strings to parse your whole module path and produce a website containing documentation on all your modules. That’s a very good way to make a start on operational documentation.