Task and concept samples: Puppet Strings

03 Jun, 2026

Context

• Organization: Puppet (open source)
• Audience: Puppet module developers
• Scope: Tasks, manifests, and annotated examples

These task topic samples are from my work documenting Puppet Strings, a tool Puppet developed to help open source module developers create better documentation for their modules.

This version of Puppet open source documentation can be accessed in its entirety in the Puppet documentation archive.

Contents

• Concept: Documenting modules with Puppet Strings
• Task: Install Puppet Strings
• Task: Publish module documentation to GitHub Pages

Documenting modules with Puppet Strings

Produce complete, user-friendly module documentation by using Puppet Strings. Strings uses tags and code comments, along with the source code, to generate documentation for a module's classes, defined types, functions, tasks, plans, and resource types and providers.

If you are a module author, add descriptive tags and comments with the code for each element (class, defined type, function, or plan) in your module. Strings extracts information from the module's Puppet and Ruby code, such as data types and attribute defaults. Whenever you update code, update your documentation comments at the same time.

Both module users and authors can generate module documentation with Strings. Even if the module contains no code comments, Strings generates minimal documentation based on the information it can extract from the code.

Strings outputs documentation in HTML, JSON, or Markdown formats:

• HTML output, which you can read in any web browser, includes the module README and reference documentation for all classes, defined types, functions, tasks, task plans, and resource types.
• JSON output includes the reference documentation only, and writes it to either STDOUT or to a file.
• Markdown output includes the reference documentation only, and writes the information to a REFERENCE.md file.

Puppet Strings is based on the YARD Ruby documentation tool.

Related information

• Documenting modules — Document any module you write, whether for internal use or publication on the Forge. Complete, clear documentation helps users understand what your module can do and how to use it.
• Puppet Strings style guide — To document your module with Puppet Strings, add descriptive tags and comments to your module code. Write consistent, clear comments, and include at least basic information about each element.

Install Puppet Strings

Before you can generate module documentation, you must install the Puppet Strings gem.

Prerequisites:

• Ruby 2.1.9 or newer
• Puppet 4.0 or newer
• The yard Ruby gem

Steps:

1. If you don't have the yard gem installed, run:

   gem install yard
   

2. Install the puppet-strings gem:

   gem install puppet-strings
   

Generating documentation with Strings

Generate documentation in HTML, JSON, or Markdown by running Puppet Strings.

Strings creates reference documentation based on the code and comments in all Puppet and Ruby source files in the following module subdirectories:

• manifests/
• functions/
• lib/
• types/
• tasks/
• plans/

By default, Strings outputs HTML of the reference information and the module README to the module's doc/ directory. If you specify JSON or Markdown output, documentation includes the reference information only. Strings writes Markdown output to a REFERENCE.md file and sends JSON output to STDOUT, but you can specify a custom file destination for either format.

Generate and view documentation in HTML

1. Change directory into the module:

   cd /modules/<MODULE_NAME>
   

2. Generate documentation:

   • To generate documentation for the entire module:

     puppet strings
     

   • To generate documentation for specific files or directories, use the puppet strings generate subcommand with a space-separated list:

     puppet strings generate first.pp second.pp
     

     puppet strings generate 'modules/apache/lib/**/*.rb' 'modules/apache/manifests/**/*.pp' 'modules/apache/functions/**/*.pp'
     

Strings outputs HTML to the doc/ directory in the module. Open index.html in that folder to view it.

To view HTML documentation for all of your local modules, run puppet strings server from any directory. This serves documentation for all modules in the module path at http://localhost:8808.

Generate and view documentation in Markdown

The reference documentation includes descriptions, usage details, and parameter information for classes, defined types, functions, tasks, plans, and resource types and providers.

Strings generates Markdown output as a REFERENCE.md file in the main module directory. You can specify a different filename or location with command line options.

1. Change directory into the module:

   cd /modules/<MODULE_NAME>
   

2. Run:

   puppet strings generate --format markdown
   

   To specify a different output file:

   puppet strings generate --format markdown --out docs/INFO.md
   

Generate documentation in JSON

Generate JSON output if you want to use the documentation in a custom application that reads JSON. By default, Strings prints JSON output to STDOUT.

1. Change directory into the module:

   cd /modules/<MODULE_NAME>
   

2. Run:

   puppet strings generate --format json
   

   To generate JSON documentation to a file instead:

   puppet strings generate --format json --out documentation.json
   

For details about Strings JSON output, see the Strings JSON schema.

Publish module documentation to GitHub Pages

To make your module documentation available on GitHub Pages, generate and publish HTML documentation with a Strings Rake task.

The strings:gh_pages:update Rake task is available in the puppet-strings/tasks directory. This task keeps the gh-pages branch up to date with your current code by performing the following actions:

1. Creates a doc directory in the root of your project, if it doesn't already exist.
2. Creates a gh-pages branch of the current repository, if it doesn't already exist.
3. Checks out the gh-pages branch.
4. Generates Strings HTML documentation.
5. Commits the documentation file and pushes it to the gh-pages branch with the --force flag.

Steps:

1. If this is the first time running this task, update your Gemfile and Rakefile:

   Add to your Gemfile:

   gem 'puppet-strings'
   

   Add to your Rakefile:

   require 'puppet-strings/tasks'
   

2. Generate, push, and publish your module's Strings documentation:

   strings:gh_pages:update
   

The documentation is published after the task pushes the updated documentation to GitHub Pages.

Open source documentation licensed under Creative Commons. Reproduced here as a professional writing sample.