399 lines
12 KiB
Markdown
399 lines
12 KiB
Markdown
Puppet Strings
|
|
==============
|
|
[](https://travis-ci.org/puppetlabs/puppet-strings) [](https://badge.fury.io/rb/puppet-strings)
|
|
|
|
A Puppet command built on [YARD](http://yardoc.org/).
|
|
|
|
Puppet Strings generates HTML documentation for Puppet extensions written in Puppet and Ruby.
|
|
|
|
This tool will eventually place the existing `puppet doc` command once feature parity has been achieved.
|
|
|
|
| | |
|
|
| -------------- |---------------------------------------------------------------- |
|
|
| *Code* | [GitHub][repo] |
|
|
| *Issues* | [Puppet JIRA Tracker][JIRA] |
|
|
| *License* | [Apache 2.0][LICENSE] |
|
|
| *Change log* | [CHANGELOG.md][changelog] |
|
|
| *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
|
|
|
|
[repo]: https://github.com/puppetlabs/puppet-strings
|
|
[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
|
|
[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
|
|
[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
|
|
[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
|
|
[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
|
|
|
|
Requirements
|
|
------------
|
|
|
|
In order to run strings you need to have the following software installed:
|
|
|
|
* Ruby 1.9.3 or newer
|
|
* Puppet 3.7 or newer
|
|
* The `yard` Ruby gem
|
|
|
|
Installing the YARD Gem
|
|
-----------------------
|
|
|
|
The easiest way to install the `yard` gem is with Puppet itself:
|
|
|
|
For Puppet 4.x:
|
|
```
|
|
$ puppet resource package yard provider=puppet_gem
|
|
```
|
|
|
|
For Puppet 3.x:
|
|
```
|
|
$ puppet resource package yard provider=gem
|
|
```
|
|
|
|
Installing Puppet Strings
|
|
-------------------------
|
|
|
|
Strings can be installed using the [puppet-strings](https://rubygems.org/gems/puppet-strings) gem.
|
|
|
|
To ensure it is installed in right place, it is best to install it using Puppet:
|
|
|
|
For Puppet 4.x:
|
|
```
|
|
$ puppet resource package puppet-strings provider=puppet_gem
|
|
```
|
|
|
|
For Puppet 3.x:
|
|
```
|
|
$ puppet resource package puppet-strings provider=gem
|
|
```
|
|
|
|
Running Puppet Strings
|
|
----------------------
|
|
|
|
Once strings has been installed you can document a puppet module:
|
|
|
|
```
|
|
$ cd /path/to/module
|
|
$ puppet strings
|
|
```
|
|
|
|
This processes `README` and all Puppet and Ruby source files under the `./manifests/`, `./functions/`, and `./lib/`
|
|
directories by default and creates HTML documentation under the `./doc/` directory.
|
|
|
|
To document specific files:
|
|
|
|
```
|
|
$ puppet strings generate first.pp second.pp ...
|
|
```
|
|
|
|
To document specific directories:
|
|
|
|
```
|
|
$ puppet strings 'modules/foo/lib/**/*.rb' 'modules/foo/manifests/**/*.pp' 'modules/foo/functions/**/*.pp' ...
|
|
```
|
|
|
|
Strings can emit JSON documenting the Puppet extensions:
|
|
|
|
```
|
|
$ puppet strings generate --emit-json documentation.json
|
|
```
|
|
|
|
It can also print the JSON to stdout:
|
|
|
|
```
|
|
$ puppet strings generate --emit-json-stdout
|
|
```
|
|
|
|
The schema for the JSON output is [documented here](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
|
|
|
|
In addition to generating a directory full of HTML, you can also serve up documentation for all your modules using the `server` action:
|
|
|
|
```
|
|
$ puppet strings server
|
|
```
|
|
|
|
YARD Options
|
|
------------
|
|
|
|
YARD options (see `yard help doc`) are supported in a `.yardopts` file in the same directory where `puppet strings` is run.
|
|
|
|
Puppet Strings automatically sets the `markup` option to `markdown`, allowing your documentation strings to be in Markdown format.
|
|
|
|
Documenting Puppet Extensions
|
|
-----------------------------
|
|
|
|
### Puppet Classes / Defined Types
|
|
|
|
To document Puppet classes and defined types, use a YARD docstring before the class or defined type definition:
|
|
|
|
```puppet
|
|
# An example class.
|
|
#
|
|
# This is an example of how to document a Puppet class
|
|
#
|
|
# @example Declaring the class
|
|
# include example
|
|
#
|
|
# @param first The first parameter for this class
|
|
# @param second The second paramter for this class
|
|
class example_class(
|
|
String $first = $example::params::first_arg,
|
|
Integer $second = $example::params::second_arg,
|
|
) inherits example::params {
|
|
# ...
|
|
}
|
|
|
|
# An example defined type.
|
|
#
|
|
# This is an example of how to document a defined type.
|
|
# @param ports The array of port numbers to use.
|
|
define example_type(
|
|
Array[Integer] $ports = []
|
|
) {
|
|
# ...
|
|
}
|
|
```
|
|
|
|
***Note: unlike Ruby, Puppet is a typed language; Puppet Strings will automatically use the parameter type information to
|
|
document the parameters. A warning will be emitted if you document parameter types.***
|
|
|
|
### Resource Types
|
|
|
|
To document custom resource types and their parameters/properties, use the `desc` method or assign a value to the `doc` attribute:
|
|
|
|
```ruby
|
|
Puppet::Type.newtype(:example) do
|
|
desc <<-DESC
|
|
An example resource type.
|
|
@example Using the type.
|
|
example { foo:
|
|
param => 'hi'
|
|
}
|
|
DESC
|
|
|
|
newparam(:param) do
|
|
desc 'An example parameter.'
|
|
# ...
|
|
end
|
|
|
|
newproperty(:prop) do
|
|
desc 'An example property.'
|
|
#...
|
|
end
|
|
|
|
# ...
|
|
end
|
|
```
|
|
|
|
Puppet Strings documents this way to preserve backwards compatibility with `puppet doc` and existing resource types.
|
|
|
|
***Note: Puppet Strings does not evaluate your Ruby code, so only certain static expressions are supported.***
|
|
|
|
To document parameters and properties that are dynamically created, use the `#@!puppet.type.param` and `#@!puppet.type.property`
|
|
directives before the `newtype` call:
|
|
|
|
```ruby
|
|
# @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter.
|
|
# @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property.
|
|
Puppet::Type.newtype(:example) do
|
|
#...
|
|
end
|
|
```
|
|
|
|
### Providers
|
|
|
|
To document providers, use the `desc` method or assign a value to the `doc` attribute:
|
|
|
|
```ruby
|
|
Puppet::Type.type(:example).provide :platform do
|
|
desc 'An example provider.'
|
|
|
|
# ...
|
|
end
|
|
```
|
|
|
|
Puppet Strings documents this way to preserve backwards compatibility with `puppet doc` and existing resource types.
|
|
|
|
***Note: Puppet Strings does not evaluate your Ruby code, so only certain static expressions are supported.***
|
|
|
|
### Functions
|
|
|
|
Puppet Strings supports three different ways of defining a function in Puppet: with the Puppet 3.x API, Puppet 4.X API,
|
|
and in the Puppet language itself.
|
|
|
|
## Puppet 3.x API
|
|
|
|
To document a function in the Puppet 3.x API, use the `doc` option to `newfunction`:
|
|
|
|
```ruby
|
|
Puppet::Parser::Functions.newfunction(:example, doc: <<-DOC
|
|
Documentation for an example 3.x function.
|
|
@param [String] param1 The first parameter.
|
|
@param [Integer] param2 The second parameter.
|
|
@return [Undef]
|
|
@example Calling the function.
|
|
example('hi', 10)
|
|
DOC
|
|
) do |*args|
|
|
#...
|
|
end
|
|
```
|
|
|
|
***Note: if parameter types are omitted, a default of the `Any` Puppet type will be used.***
|
|
|
|
## Puppet 4.x API
|
|
|
|
To document a function in the Puppet 4.x API, use a YARD docstring before the `create_function` call and any `dispatch`
|
|
calls:
|
|
|
|
```ruby
|
|
# An example 4.x function.
|
|
Puppet::Functions.create_function(:example) do
|
|
# @param first The first parameter.
|
|
# @param second The second parameter.
|
|
# @return [String] Returns a string.
|
|
# @example Calling the function
|
|
# example('hi', 10)
|
|
dispatch :example do
|
|
param 'String', :first
|
|
param 'Integer', :second
|
|
end
|
|
|
|
# ...
|
|
end
|
|
```
|
|
|
|
***Note: Puppet Strings will automatically use the parameter type information from the `dispatch` block to document
|
|
the parameters. Only document your parameter types when the Puppet 4.x function contains no `dispatch` calls.***
|
|
|
|
If the Puppet 4.x function contains multiple `dispatch` calls, Puppet Strings will automatically create `overload` tags
|
|
to describe the function's overloads:
|
|
|
|
```ruby
|
|
# An example 4.x function.
|
|
Puppet::Functions.create_function(:example) do
|
|
# Overload by string.
|
|
# @param first The first parameter.
|
|
# @return [String] Returns a string.
|
|
# @example Calling the function
|
|
# example('hi')
|
|
dispatch :example_string do
|
|
param 'String', :first
|
|
end
|
|
|
|
# Overload by integer.
|
|
# @param first The first parameter.
|
|
# @return [Integer] Returns an integer.
|
|
# @example Calling the function
|
|
# example(10)
|
|
dispatch :example_integer do
|
|
param 'Integer', :first
|
|
end
|
|
|
|
# ...
|
|
```
|
|
|
|
The resulting HTML for this example function will document both `example(String $first)` and `example(Integer $first)`.
|
|
|
|
## Puppet Language
|
|
|
|
To document Puppet functions written in the Puppet language, use a YARD docstring before the function definition:
|
|
|
|
```puppet
|
|
# An example function written in Pupppet.
|
|
# @param name The name to say hello to.
|
|
# @return [String] Returns a string.
|
|
# @example Calling the function
|
|
# example('world')
|
|
function example(String $name) {
|
|
"hello $name"
|
|
}
|
|
```
|
|
|
|
***Note: Puppet Strings will automatically use the parameter type information from the function's parameters to document
|
|
the parameters.***
|
|
|
|
Additional Resources
|
|
--------------------
|
|
|
|
Here are a few other good resources for getting started with documentation:
|
|
|
|
* [Module README Template](https://docs.puppet.com/puppet/latest/reference/modules_documentation.html)
|
|
* [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
|
|
* [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
|
|
|
|
Rake Tasks
|
|
----------
|
|
|
|
Puppet Strings comes with two rake tasks: `strings:generate` and `strings:gh_pages:update` available in `puppet-strings/tasks`.
|
|
|
|
Add the following to your Gemfile to use `puppet-strings`:
|
|
|
|
```ruby
|
|
gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git'
|
|
```
|
|
|
|
In your `Rakefile`, add the following to use the `puppet-strings` tasks:
|
|
|
|
```ruby
|
|
require 'puppet-strings/tasks'
|
|
```
|
|
|
|
The `strings:generate` task can be used to generate documentation:
|
|
|
|
```
|
|
$ rake strings:generate
|
|
```
|
|
|
|
The task accepts the following parameters:
|
|
|
|
* `patterns`: the search patterns to use for finding files to document (defaults to `manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb`).
|
|
* `debug`: enables debug output when set to `true`.
|
|
* `backtrace`: enables backtraces for errors when set to `true`.
|
|
* `markup`: the markup language to use (defaults to `markdown`).
|
|
* `yard_args`: additional arguments to pass to YARD.
|
|
|
|
An example of passing arguments to the `strings:generate` Rake task:
|
|
|
|
```
|
|
$ rake strings:generate\['**/*.pp **/*.rb, true, true, markdown, --readme README.md']
|
|
```
|
|
|
|
The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will:
|
|
|
|
1. Create a `doc` directory in the root of your project
|
|
2. Check out the `gh-pages` branch of the current repository in the `doc` directory (it will create a branch if one does not already exist)
|
|
3. Generate strings documentation using the `strings:generate` task
|
|
4. Commit the changes and push them to the `gh-pages` branch **with the `--force` flag**
|
|
|
|
This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch.
|
|
***Please note this operation will be destructive if not used properly.***
|
|
|
|
Developing and Contributing
|
|
---------------------------
|
|
|
|
We love contributions from the community!
|
|
|
|
If you'd like to contribute to the strings module, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/master/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, simply execute the `spec` rake task:
|
|
|
|
$ bundle install --path .bundle/gems
|
|
$ bundle exec rake spec
|
|
|
|
Support
|
|
-------
|
|
|
|
Please log tickets and issues at our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users)
|
|
is available for asking questions and getting help from others.
|
|
|
|
There is also an active #puppet channel on the Freenode IRC network.
|
|
|
|
We use semantic version numbers for our releases, and recommend that users stay as up-to-date as possible by upgrading 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.
|