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.
Puppet Strings is pretty easy to install. It’s under regular development though so you should be sure to keep it up to date.
The installation has a few prerequisites. You will need:
- Ruby 1.9.3 or newer installed.
- Puppet 3.7 or newer installed.
yard Ruby Gem.
Installing Puppet Strings
You can install Puppet Strings using the
puppet module command:
Or by cloning the Git repository into the Puppet module path, for example:
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 will process the contents of your
README.md1, 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:
You can also easily add your documentation to GitHub as a Pages site as we’ve done here with the Sensu Puppet module.
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.
You have a
README.mdin your module right? You really, really should. ↩︎