Meet Puppet Strings 2.0.0
First of all, we should come clean. Years ago, we asked everyone to start using Puppet Strings but didn’t actually get around to using it ourselves. We didn’t provide a spec for the comment style or much support for generated documentation. Our aim with Strings 2.0.0 is to change both of those things and more.
New to Puppet Strings?
Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby. Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
Here is an example manifest with Puppet Strings comments added:
You can run Puppet Strings on your entire module (commented or not) to...
Here is sample HTML output from the sample manifest above:
Why is Puppet Strings such a big deal?
The hard truth is that it’s difficult to keep your module’s documentation up to date as things change over time. We know that most users coming to the Puppet Forge are looking for module documentation. If you want people to use your module, it’s important to have complete and accurate docs.
With Puppet Strings, it’s a lot easier to keep your module docs both accurate and complete because they live in your module’s source code. Whether you’re adding a new parameter or refactoring a custom type, you won’t have to go to a separate document to update your documentation. Also, Puppet Strings provides enough structure so that your docs are more paint by numbers than painting a portrait on a blank canvas.
Style guide on puppet.com
Thanks to contributions from the community and our tech pubs team, the new Puppet Strings style guide is on puppet.com/docs. One thing we heard from you was that there should be a standard for writing Strings documentation in source code. We’ve attempted to answer that call and hopefully you find it useful.
In the new style guide, you can view recommended layouts for Strings-style comments for every type of file you want to document (classes, defined types, functions, etc.) and read about each available documentation tag. If you're looking for a how-to guide, check out the Puppet Strings docs.
Document Puppet tasks and plans
In Puppet Strings 2.0.0, you can document your Puppet plans using YARD-style comments. We also added Puppet task support in version 1.2.0. In the case of tasks, Strings will consume the task JSON directly for generating output instead of using tags. Plans can be documented like other Puppet files:
The new REFERENCE.md pattern
This was actually added in 1.2.0, but I wanted to mention it anyway: In addition to JSON and HTML, you can now generate Markdown with Puppet Strings.
In Puppet Supported modules, we are going to start generating this Markdown (which defaults to
./REFERENCE.md) in the root of the module. This will serve two purposes. First, we will have a standardized, easily digested, and isolated Reference file for each module. Second, we will be able to remove this information from the README.md, which allows for much shorter READMEs and less documentation to maintain all around. The Forge now uses Strings-generated docs on the module detail page! If your module contains the REFERENCE.md file, the Forge displays it in a Reference tab. That means users can always get to your module's docs on the Forge, and you don't have to update reference information in your README.
We're really excited to implement this pattern, and we're interested to know what you think of it.
Drops old version support
Finally the boring stuff. To catch up with Supported Modules, we're going to be moving to a minimum Ruby version of 2.1.9, and we will no longer be supporting Puppet 3 (the parser, essentially). You may continue to use Strings with Puppet 3 functions (we won't be ripping compatibility out right away), but we won't address issues concerning Puppet 3 any longer.
Puppet Development Kit provides some Strings-style comments built into generated classes, types, and more to get you started right off the bat. In the future, Strings may be baked right into PDK for more streamlined usage.
We’ve got more plans for Strings coming up later this year, like adding support for a few new tags and expanding the types of files Strings can document (think facts and type aliases).
As always, thanks to you, the community, for all that you do. We’re eager to hear about how you’re using Strings in your workflow! You can find us on Slack in #forge-modules or submit a ticket under the PDOC project on tickets.puppet.com.
Eric Putnam is a software engineer at Puppet.