openvox-strings

openvox-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.

It's a fork of https://github.com/puppetlabs/puppet-strings.

• Ruby 3.2 or newer
• OpenVox 8.24 or newer

For detailed dependencies, please checkout the gemspec file.

Installation instructions vary slightly depending on how you have installed OpenVox:

Install the openvox-strings gem into the openvox-agent environment:

sudo /opt/puppetlabs/puppet/bin/gem install openvox-strings

Install the openvox-strings gem into the same Ruby installation where you have installed the openvox gem:

gem install openvox-strings

To use YARD options with Strings, specify a .yardopts file in the same directory in which you run puppet strings.

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.

By default, 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 OpenVox Strings documentation for complete instructions for generating documentation with Strings.

For code comment style guidelines and examples, see the OpenVox Strings style guide.

Here are a few other good resources for getting started with documentation:

• Module README Template
• YARD Getting Started Guide
• YARD Tags Overview

We love contributions from the community!

If you'd like to contribute to openvox-strings, check out CONTRIBUTING.md to get information on the contribution process.

If you plan on developing features or fixing bugs in openvox-strings, it is essential that you run specs before opening a pull request.

To run specs, run the spec rake task:

bundle config set --local path .bundle/gems
bundle install
bundle exec rake spec

To run acceptance tests, run the acceptance rake task:

bundle config set --local path .bundle/gems
bundle install
bundle exec rake acceptance

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.

Please log issues in GitHub issues. Check out CONTRIBUTING.md for tips on writing the best issues.

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.