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

@author
List the author or authors of a class, module, or method.
# @author Foo Bar
class MyClass; end
@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 is 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.