Open source Puppet documentation

Document any module you write, whether your module is for internal use only or for publication on the Puppet Forge. Complete, clear documentation helps your module users understand what your module can do and how to use it.

When writing module documentation, base your README on our module README template and use Puppet Strings to generate reference information for your module’s classes, defined types, functions, tasks, task plans, and resource types and providers.

Related topics:

The README

In your README, include basic module information and extended usage examples for the most common use cases. Your README should tell users what your module does and how they can use it.

Include reference information as a separate REFERENCE.md file in the module’s root directory. This file should include a complete list of your module’s elements: classes, defined types, functions, resource types and providers, Puppet tasks and plans, and parameters for each element. If you upload your module to the Forge, this reference information is displayed in a Reference tab on the module detail page. To make sure your docs stay current, use Puppet Strings to generate the REFERENCE.md page based on your code and comments.

Strings does not generate information for type aliases or facts. If your module includes these elements, document them in your README.

Write your README in Markdown and use the .md or .markdown extension for the file. The README should contain the following sections:

  • Module description: What the module does and why it is useful.
  • Setup: Prerequisites for module use and getting started information.
  • Usage: Instructions and examples for common use cases or advanced configuration options.
  • Reference: If the module contains facts or type aliases, include them in a short supplementary Reference section. All other reference information, such as classes and their parameters, are in the REFERENCE.md file generated by Strings.
  • Limitations: OS compatibility and known issues.
  • Development: Guide for contributing to the module.

If you used Puppet Development Kit (or the deprecated puppet module generate command) to generate your module, you already have a copy of the README template in .md format in your module. You can also use the standalone template to guide you.

Related topics:

Creating a table of contents

The table of contents helps your users find their way around your module README.

Start with the module name as a Level 1 heading at the top of the module, followed by “Table of Contents” as a Level 4 heading. Under the table of contents heading, include a numbered list of top-level sections, with any necessary subsections in a bulleted list below the section heading. Link each section to its corresponding heading in the README.


    # modulename

    #### Table of Contents

    1. [Module Description - What the module does and why it is useful](#module-description)
    2. [Setup - The basics of getting started with [modulename]](#setup)
        * [What [modulename] affects](#what-[modulename]-affects)
        * [Setup requirements](#setup-requirements)
        * [Beginning with [modulename]](#beginning-with-[modulename])
    3. [Usage - Configuration options and additional functionality](#usage)
    4. [Limitations - OS compatibility, etc.](#limitations)
    5. [Development - Guide for contributing to the module](#development)

Writing the module description

In your module Description, briefly tell users why they might want to use your module. Explain what your module does and what kind of problems users can solve with it.

This should be a fairly short description helps the user decide if your module is what they want. What are the most common use cases for your module? Does your module just install software? Does it install and configure it? Give your user information about what to expect from the module.

## Module description

The `cat` module installs, configures, and maintains your cat in both apartment and residential house settings.

The cat module automates the installation of a cat to your apartment or house, and then provides options for configuring the cat to fit your environment's needs. Once installed and configured, the cat module automates maintenance of your cat through a series of resource types and providers.

Writing the Setup section

In the Setup section, detail how your user can successfully get your module functioning. Include steps to get started, requirements, and any other information users might need to know before they start using your module.

Module installation instructions are covered both on the module’s Forge page and in the Puppet docs, so don’t reiterate them here. In this section, include the following subsections, as applicable:

  • What (modulename) affects

    Include this section only if:

    • The module alters, overwrites, or otherwise touches files, packages, services, or operations other than the named software; OR
    • The module’s general performance can overwrite, purge, or otherwise remove entries, files, or directories in a user’s environment.

    For example:

    ## Setup
    
    ### What cat affects
    
    * Your dog door might be overwritten if not secured before installation.
    
  • Setup Requirements

    Include this section only if the module requires additional software or some tweak to a user’s environment. For instance, the firewall module uses Ruby-based providers which required pluginsync to be enabled.

  • Beginning with [modulename]

    Always include this section to explain the minimum steps required to get the module up and running in a user’s environment. You can use basic Proof of Concept use cases here; it doesn’t have to be something you would run in production. For simple modules, “Declare the main ::cat class” may be enough.

    ### Beginning with cat
    
    Declare the main `::cat` class.
    

Writing the Usage section

Include usage examples for common use cases in the Usage section. Show your users how to use your module to solve problems, and be sure to include code examples.

If your module does many things, include three to five examples of the most important or common tasks a user can accomplish with your module. Show users how to accomplish more complex tasks that involve different types, classes, and functions working in tandem. For example, the Usage section for the puppetlabs-apache module includes an example that shows users how to set up a virtual host with SSL, which involves several classes.

## Usage

You can manage all interaction with your cat through the main `cat` class. With the default options, the module installs a basic cat with no optimizations.

### I just want cat, what's the minimum I need?

    include '::cat'

### I want to configure my lasers

Use the following to configure your lasers for a random-pattern, 20-minute playtime at 3 a.m. local time.

    class { 'cat':
      laser => {
        pattern    => 'random',
        duration   => '20',
        start_time => '0300',
      }
    }

Writing the limitations and development sections

In the Limitations section, warn your users of issues, and the Development section tells your users how they can contribute to your module.

In the Limitations section, list any incompatibilities, known issues, or other warnings.

## Limitations

This module cannot be used with the smallchild module.

In the Development section, tell other users the ground rules for contributing to your project and how they should submit their work.

Generating Reference documentation with Strings

List reference information — that is, a complete list of classes, defined types, functions, resource types and providers, tasks, and plans — in a separate REFERENCE.md file in the root directory of your module. Use Puppet Strings to generate this documentation based on your comments and module code. If you aren’t using Strings to generate documentation yet, you can create a REFERENCE.md file manually.

Previously, we recommended that module authors include reference information in the README itself. However, the Reference section often became quite long and difficult to maintain. Moving reference information to a separate file keeps the README more readable, and using Strings to generate this file should alleviate maintenance work. The Forge displays information from a module’s REFERENCE.md file in a Reference tab on the module detail page, so the information remains easily accessible to users.

To transition your module to the REFERENCE.md model, add Strings comments to your code for each of your classes, defined types, functions, task plans, and resource types and providers. You can create a REFERENCE.md file manually, but remember that if you generate a REFERENCE.md with Strings, it will overwrite any existing REFERENCE.md file. For details on adding comments to your code, see the Puppet Strings style guide. For instructions on how to install and use Strings, see the Puppet Strings documentation.

Manually writing reference information

If you’re not yet ready to use Puppet Strings to generate your reference docs, you can manually create a REFERENCE.md file listing all of your module’s classes, defined types, functions, tasks, task plans, and resource types and providers. This is useful if you are in the process of moving your reference documentation into code comments, or if your module contains resources that aren’t yet supported in Strings.

If your module contains a REFERENCE.md file, the Forge displays the contents in a Reference tab on the module’s detail page, whether you created the file manually or with Strings. Write the REFERENCE.md file in Markdown, and keep it in the root directory of your module.

If you already have a README with an accurate reference section, you can remove that section from your README and paste it into a REFERENCE.md file. The formatting isn’t vastly different.

Important: If you create a REFERENCE.md manually, and then generate Markdown with Puppet Strings, it will overwrite your REFERENCE.md unless you give the files different names. The module detail page on the Forge displays only the README.md and REFERENCE.md files.

At the top of your REFERENCE.md, include a ` # Reference` header and a table of contents.

In the table of contents, list each element of your module: classes, defined types, functions, tasks, task plans, and resource types and providers. Provide brief descriptions, and separate public and private classes.

Include the following information:

  • The data type, if applicable.
  • A description of what the element does.
  • Valid values, if the data type doesn’t make it obvious.
  • Default value, if any.
# Reference

## Classes

### Public Classes
*[`cat`](#cat)

### Private Classes
*`cat::install`: Handles the cat packages.
*`cat::configure`: Handles the configuration file.
*`cat::service`: Handles the cat service for maintenance of your cat.

In the body of the REFERENCE.md, list out each of the module’s elements (classes, defined types, functions, and so on), describe what it does, and list out its parameters.

For each parameter, list:

  • If the parameter is required, specify Required.
  • The data type.
  • A description of what the parameter does, along with other information the user might need, such as “Only applies if perl_enable => true.”
  • The valid values for the parameter, unless evident from the data type. For example, for a String data type, you should list specify what kind of string is needed (such as one of a specific set of strings or a valid URL). For a Boolean data type, you don’t need to list true and false as valid values.
  • The default value.
### Class: cat

Installs and configures a cat in your environment.

#### Parameters

The following parameters are available in the `cat` class:

##### `purr`

Data type: `Boolean`.

Enables purring in your cat.

Default: `true`.

##### `meow`

Data type: `Any`.

Enables vocalization in your cat.

Valid values: 'loud', 'medium-loud', 'kitten', 'silent'.

Default: 'medium-loud'.

Documentation style

To write a clear, concise, and comprehensible documentation, we recommend following a few principles, best practices, and style guidelines.

  1. Write for both web and terminal viewing using Markdown. Above all else, your module must be easily readable and scannable.
  2. Limit the number of external links. Linking to anything on the web limits the usability of the module, particularly when users read it in terminal.
  3. Consistency is key. Consistently formatted documentation means that no matter the module, users know where to get the information they’re looking for.
  4. Use the second person; that is, write directly to the person reading your document. For example, “If you’re installing the cat module on Windows…”
  5. Use the imperative; that is, tell the user what they should do. For example, “Secure your dog door before installing the cat module.”
  6. Use the active voice whenever possible. For example, “Install cat and bird modules on separate instances” rather than “The cat and bird modules should be installed on separate instances.”
  7. Use the present tense, almost always. Use present tense for parameter behaviors (such as “Enables…” or “Specifies…”) and for events that regularly occur (such as “This parameter sets your cat to ‘purebred’. The purebred cat alerts you for breakfast at 6 a.m.” Use future tense only when you are specifically referring to something that takes place at a time in the future, such as “The tail parameter is deprecated and will be removed in a future version. Use manx instead.”

Puppet module documentation conventions

At Puppet, we follow some documentation conventions to make our docs clear and to make it easier to translate our module READMEs and REFERENCEs into other languages. While you aren’t required to use the same conventions in your own modules, we ask that you use them when submitting documentation changes to modules owned by Puppet.

The Forge’s Markdown rendering is exactly the same as GitHub’s rendering.

  1. Lowercase module names, such as apache. This helps differentiate the module from the software the module is automating. Capitalize software names as they normally would be, such as Apache.
  2. String values are set in single quotes, to indicate that they are strings.
  3. The values true, false, and undef are set in backticks.
  4. Filenames, settings, directories, classes, types, defined types, functions, and similar code elements are set in backticks, unless they are being passed as a string value. When indicating any value that the user passes as a string, use quotes.
  5. Integer values require no special marking.
  6. Data types are set in backticks.
  7. Use empty lines between new lines to help with readability.
Back to top