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.

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.

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

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.

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

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

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'] ), } )

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.

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

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.

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