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.
|Contributing||CONTRIBUTING.md and COMMITTERS.md|
Installing Puppet Strings
- Ruby 2.1.9 or newer
- Puppet 4.0.0 or newer
Install Puppet Strings
Installation instructions vary slightly depending on how you have installed Puppet:
Installing Puppet Strings with
puppet-strings gem into the
sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings
Installing Puppet Strings with standalone
puppet-strings gem into the same Ruby installation where you have installed the
gem install puppet-strings
Configure Puppet Strings (Optional)
To use YARD options with Puppet Strings, specify a
.yardopts file in the same directory in which you run
puppet strings. Puppet Strings supports the Markdown format and automatically sets the YARD
markup option to
To see a list of available YARD options, run
yard help doc. For details about YARD options configuration, see the YARD docs.
Generating documentation with Puppet Strings
By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead.
Strings generates reference documentation based on the code and Strings code comments in all Puppet and Ruby source files under the
Strings outputs HTML of the reference information and the module README to the module's
./doc/ directory. This output can be rendered in any browser.
JSON and Markdown output include the reference documentation only. Strings sends JSON output to either STDOUT or to a file. Markdown output is written to a REFERENCE.md file in the module's main directory.
Here are a few other good resources for getting started with documentation:
Developing and Contributing
We love contributions from the community!
If you'd like to contribute to
puppet-strings, check out CONTRIBUTING.md to get information on the contribution process.
If you plan on developing features or fixing bugs in Puppet Strings, it is essential that you run specs before opening a pull request.
To run specs, run the
spec rake task:
$ bundle install --path .bundle/gems $ bundle exec rake spec
Running Acceptance Tests
We are experimenting with a new tool for running acceptance tests. It's name is puppet_litmus and replaces beaker as the test runner.
An example of running the acceptance tests locally with Docker:
Ensure Docker is installed and running.
Install Ruby gems. This step can be skipped if you have already followed the Running Specs instructions
$ bundle install --path .bundle/gems
- Provision a docker container, in this case CentOS 7
$ bundle exec rake litmus:provision[docker, centos:7]
- Install test items; Puppet Agent, our test module, and the puppet-strings gem built from this source code
$ bundle exec rake litmus:install_agent[puppet6] $ bundle exec rake litmus:install_module_fixtures $ bundle exec rake litmus:install_gems
- Run the acceptance tests. These tests can be run more than once without the need to run the provisioning steps again
$ bundle exec rake litmus:acceptance:parallel
- Remove any test containers
$ bundle exec rake litmus:tear_down
An example of run the acceptance tests follow the instructions [here].
A mailing list is available for asking questions and getting help from others.
There is also an active community on the Puppet community Slack in the #forge-modules channel.
We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.