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.
Installing Puppet
Strings¶ ↑
Requirements¶ ↑
-
Ruby 3.1.0 or newer
-
Puppet
8.0.0 or newer
Install Puppet
Strings¶ ↑
Installation instructions vary slightly depending on how you have installed Puppet:
Installing Puppet
Strings with {puppet-agent
} package¶ ↑
Install the puppet-strings
gem into the puppet-agent
environment:
sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings
Installing Puppet
Strings with standalone puppet
gem¶ ↑
Install the puppet-strings
gem into the same Ruby installation where you have installed the puppet
gem:
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 markdown
.
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 ./manifests/
, ./functions/
, ./lib/
, ./types/
, and ./tasks/
directories.
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.
See the Puppet Strings documentation for complete instructions for generating documentation with Strings.
For code comment style guidelines and examples, see the Puppet Strings style guide.
Additional Resources¶ ↑
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.
Running Specs¶ ↑
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¶ ↑
Acceptance tests can be executed with puppet_litmus.
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 codebundle exec rake 'litmus:install_agent[puppet8]' bundle exec rake 'litmus:install_modules_from_directory[./spec/fixtures/acceptance/modules]' 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
License¶ ↑
This codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.
Support¶ ↑
Please log issues in GitHub issues. Check out CONTRIBUTING.md for tips on writing the best issues.
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.