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. To learn more about YARD, see the YARD documentation.

Install Puppet Strings

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

Before you begin

Puppet Strings requires:

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

If you don't have the yard gem installed yet, install it by running gem install yard
Install the puppet-strings gem by running 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/

By default, Strings outputs HTML of the reference information and the module README to the module's doc/ directory. You can open and read the generated HTML documentation in any browser. 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 Markdown and JSON output.

Generate and view documentation in HTML

To generate HTML documentation for a Puppet module, run Strings from that module's directory.

Change directory into the module by running cd /modules/<MODULE_NAME>
Generate documentation with the puppet strings command:
1. To generate the documentation for the entire module, run puppet strings
2. To generate the documentation for specific files or directories in a module, run the puppet strings generate subcommand, and specify the files or directories as a space-separated list.
  For example:
```
puppet strings generate first.pp second.pp
```
```
puppet strings generate 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp'
```

Results

Strings outputs HTML to the doc/ directory in the module. To view the generated HTML documentation for a module, open the index.html file in the module's doc/ folder. To view HTML documentation for all of your local modules, run puppet strings server from any directory. This command serves documentation for all modules in the module path at http://localhost:8808. To learn more about the modulepath, see the modulepath documentation.

Generate and view documentation in Markdown

To generate reference documentation in Markdown, specify the markdown format when you run Puppet Strings.

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, but you can specify a different filename or location with command line options.

Change directory into the module: cd /modules/<MODULE_NAME>
Run the command: puppet strings generate --format markdown . To specify a different file, use the --out option and specify the path and filename:
```
puppet strings generate --format markdown --out docs/INFO.md
```

Results

View the Markdown file by opening it in a text editor or Markdown viewer.

Generate documentation in JSON

To generate reference documentation as JSON output to a file or to standard output, specify the json format when you run Strings.

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. For details about Strings JSON output, see the Strings JSON schema.

Change directory into the module: cd /modules/<MODULE_NAME>
Run the command: puppet strings generate --format json . To generate JSON documentation to a file instead, use the --out option and specify a filename:
```
puppet strings generate --format json --out documentation.json
```

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 Rake task keeps the gh-pages branch up to date with your current code, performing the following actions:

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

To learn more about publishing on GitHub Pages, see the GitHub Pages documentation.

If this is the first time you are running this task, you must first update your Gemfile and Rakefile.
1. Add the following to your Gemfile to use puppet-strings: ruby gem 'puppet-strings'
2. Add the following to your Rakefile to use the puppet-strings tasks: ruby require 'puppet-strings/tasks'
To generate, push, and publish your module's Strings documentation, run strings:gh_pages:update

Results

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

Puppet Strings command reference

Modify the behavior of Puppet Strings by specifying command actions and options.

`puppet strings` command

Generates module documentation based on code and code comments. By default, running puppet strings generates HTML documentation for a module into a ./doc/ directory within that module.

To pass options or arguments, such as specifying Markdown or JSON output, use the generate action.

Usage:

puppet strings [--generate] [--server]

Action	Description
`generate`	Generates documentation with any specified parameters, including format and output location.
`server`	Serves documentation locally at `http://localhost:8808` for all modules in the modulepath. For information about the modulepath, see the modulepath documentation.

`puppet strings generate` action

Generates documentation with any specified parameters, including format and output location.

Usage:

puppet strings generate [--format <FORMAT>][--out <DESTINATION>] [<ARGUMENTS>]

For example:

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

puppet strings generate manifest1.pp manifest2.pp

Option	Description	Values	Default
`--format`	Specifies a format for documentation.	Markdown, JSON	If not specified, outputs HTML documentation.
`--out`	Specifies an output location for documentation.	A valid directory location and filename.	If not specified, outputs to default locations depending on format: HTML: `./doc/` Markdown: main module directory) JSON: `STDOUT`
Filenames or directory paths	Outputs documentation for only specified files or directories.	Valid filenames or directory paths	If not specified, outputs documentation for the entire module.
`--debug`, `-d`	Logs debug information.	None.	If not specified, does not log debug information.
`--help`	Displays help documentation for the command.	None.	If specified, returns help information.
`--markup <FORMAT>`	The markup format to use for documentation	"markdown" "textile" "rdoc" "ruby" "text" "html" "none"	If no `--format` is specified, outputs HTML.
`--verbose`, `-v`	Logs verbosely.	None.	If not specified, logs basic information.

`puppet strings server` action

Serves documentation locally at http://localhost:8808 for all modules in the module path.

Usage:

puppet strings server [--markup <FORMAT>][[module_name]...][--modulepath <PATH>]

For example:

puppet strings server --modulepath path/to/modules

puppet strings server concat

Option	Description	Values	Default
`--markup <FORMAT>`	The markup format to use for documentation	"markdown" "textile" "rdoc" "ruby" "text" "html" "none"	If no `--format` is specified, outputs HTML.
`--debug`, `-d`	Logs debug information.	None.	If not specified, does not log debug information.
`--help`	Displays help documentation for the command.	None.	If specified, returns help information.
`Module name`	Generates documentation for the named module only.	A valid module name.	If not specified, generates documentation for all modules in the modulepath.
`--modulepath`	Puppet option for setting the modulepath.	A valid path.	Defaults to the module path specified in the `puppet.conf` file.
`--verbose`, `-v`	Logs verbosely.	None.	If not specified, logs basic information.

Available Strings tags

@api

Describes the resource as belonging to the private or public API. To mark a module element, such as a class, as private, specify as private:

# @api private

@example

Shows an example snippet of code for an object. The first line is an optional title, and any subsequent lines are automatically formatted as a code snippet. Use for specific examples of a given component. Use one example tag per example.

@param

Documents a parameter with a given name, type and optional description.

@!puppet.type.param

Documents dynamic type parameters. See the documenting resource types in the Strings style guide for detailed information.

@!puppet.type.property

Documents dynamic type properties. See the documenting resource types in the Strings style guide for detailed information.

@option

Used with a @param tag to defines what optional parameters the user can pass in an options hash to the method. For example:

  # @param [Hash] opts
  #      List of options
  # @option opts [String] :option1
  #      option 1 in the hash
  # @option opts [Array] :option2
  #      option 2 in the hash

@raise

Documents any exceptions that can be raised by the given component. For example:

 # @raise PuppetError this error will be raised if x

@return

Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if". For example:

# An example 4.x function.
   Puppet::Functions.create_function(:example) do
     # @param first The first parameter.
     # @param second The second parameter.
     # @return [String] If second argument is less than 10, the name of one item.
     # @return [Array] If second argument is greater than 10, a list of item names.
     # @example Calling the function.
     #   example('hi', 10)
     dispatch :example do
       param 'String', :first
       param 'Integer', :second
     end
     # ...
   end

@see

Adds "see also" references. Accepts URLs or other code objects with an optional description at the end. The URL or object is automatically linked by YARD and does not need markup formatting. Appears in the generated documentation as a "See Also" section. Use one tag per reference, such as a website or related method.

@since

Lists the version in which the object was first added. Strings does not verify that the specified version exists. You are responsible for providing accurate information.

@summary

A description of the documented item, of 140 characters or fewer.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.

Documenting modules with Puppet Strings

Install Puppet Strings

Generating documentation with strings

Generate and view documentation in HTML

Generate and view documentation in Markdown

Generate documentation in JSON

Publish module documentation to GitHub Pages

Puppet Strings command reference

puppet strings command

puppet strings generate action

puppet strings server action

Available Strings tags

`puppet strings` command

`puppet strings generate` action

`puppet strings server` action