ansible-specdoc

A utility for dynamically generating documentation from an Ansible module's spec.

This project was primarily designed for the Linode Ansible Collection.

An example Ansible Collection using ansible-specdoc can be found here.

Security Warning

Do not use this tool in automation or with untrusted input sources.

This tool imports and executes arbitrary Python code from the input file provided with -i/--input_file or from stdin via --stdin. Any input source can result in arbitrary code execution. Only use this tool with trusted code and in a safe environment.

Usage

ansible-specdoc [-h] [-s] [-n MODULE_NAME] [-i INPUT_FILE] [-o OUTPUT_FILE] [-f {yaml,json,jinja2}] [-j] [-t TEMPLATE_FILE]

Generate Ansible Module documentation from spec.

options:
  -h, --help            show this help message and exit
  -s, --stdin           Read the module from stdin.
  -n MODULE_NAME, --module-name MODULE_NAME
                        The name of the module (required for stdin)
  -i INPUT_FILE, --input_file INPUT_FILE
                        The module to generate documentation from.
  -o OUTPUT_FILE, --output_file OUTPUT_FILE
                        The file to output the documentation to.
  -f {yaml,json,jinja2}, --output_format {yaml,json,jinja2}
                        The output format of the documentation.
  -j, --inject          Inject the output documentation into the `DOCUMENTATION`, `RETURN`, and `EXAMPLES` fields of input module.
  -t TEMPLATE_FILE, --template_file TEMPLATE_FILE
                        The file to use as the template for templated formats.
  -c, --clear_injected_fields,
                        Clears the DOCUMENTATION, RETURNS, and EXAMPLES fields in specified module and sets them to an empty string.

Generating a templated documentation file:

ansible-specdoc -f jinja2 -t path/to/my/template.md.j2 -i path/to/my/module.py -o path/to/output/file.md

Dynamically generating and injecting documentation back into module constants:

ansible-specdoc -j -i path/to/my/module.py

NOTE: Documentation string injection requires that you have DOCUMENTATION, RETURN, and EXAMPLES constants defined in your module.

Generating a raw documentation string (not recommended):

ansible-specdoc -f yaml -i path/to/my/module.py

Implementation

Importing SpecDoc Classes

All of the ansible-specdoc classes can be imported into an Ansible module using the following statement:

from ansible_specdoc.objects import *

Alternatively, only specific classes can be imported using the following statement:

from ansible_specdoc.objects import SpecDocMeta, SpecField, SpecReturnValue, FieldType, DeprecationInfo

Declaring Module Metadata

The ansible-specdoc specification format requires that each module exports a SPECDOC_META object with the following structure:

SPECDOC_META = SpecDocMeta(
    description=['Module Description'],
    requirements=['python >= 3.6'],
    author=['Author Name'],
    options=module_spec,
    examples=[
        'example module usage'
    ],
    return_values={
        'my_return_value': SpecReturnValue(
            description='A generic return value.',
            type=FieldType.string,
            sample=['sample response']
        ),
    }
)

Declaring Argument Specification

Each SpecField object translates to a parameter that can be rendered into documentation and passed into Ansible for specification. These fields should be declared in a dict format as shown below:

module_spec = {
    'example_argument': SpecField(
        type=FieldType.string,
        required=True,
        description=['An example argument.']
    )
}

This dict should be passed into the options field of the SPECDOC_META declaration.

Passing Specification to Ansible

In order to retrieve the Ansible-compatible spec dict, use the SPECDOC_META.ansible_spec property.

Other Notes

To prevent ansible-specdoc from executing module code, please ensure that all module logic executes using the following pattern:

if __name__ == '__main__':
    main()

To deprecate a module, specify the deprecated field as follows:

SPECDOC_META = SpecDocMeta(
    ...
    deprecated=DeprecationInfo(
        alternative='my.new.module',
        removed_in='1.0.0',
        why='Reason for deprecation'
    )
)

When deprecating a module, you will also need to update your meta/runtime.yml file. Please refer to the official Ansible deprecation documentation for more details.

Templates

This repository provides an example Markdown template that can be used in conjunction with the -t argument.