Documenting Your Module¶

Copyright¶

The beginning of every module should look about the same. After the shebang, there should be at least two lines covering copyright and licensing of the code.

#!/usr/bin/python

# Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

Every file should have a copyright line (see The copyright notice) with the original copyright holder. Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal questions need to review the source control history, so an exhaustive copyright header is not necessary.

The license declaration should be ONLY one line, not the full GPL prefix. If you notice a module with the full prefix, feel free to switch it to the one-line declaration instead.

When adding a copyright line after completing a significant feature or rewrite, add the newer line above the older one, like so:

#!/usr/bin/python

# Copyright: (c) 2017, [New Contributor(s)]
# Copyright: (c) 2015, [Original Contributor(s)]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

ANSIBLE_METADATA Block¶

ANSIBLE_METADATA contains information about the module for use by other tools. At the moment, it informs other tools which type of maintainer the module has and to what degree users can rely on a module’s behaviour remaining the same over time.

For new modules, the following block can be simply added into your module

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'community'}

ANSIBLE_METADATA = {
    'metadata_version': '1.1',
    'supported_by': 'community',
    'status': ['preview', 'deprecated']
}

DOCUMENTATION Block¶

See an example documentation string in the checkout under examples/DOCUMENTATION.yml.

Include it in your module file like this:

#!/usr/bin/python
# Copyright (c) 2017 [REPLACE THIS]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION = '''
---
module: modulename
short_description: This is a sentence describing the module
# ... snip ...
'''

The following fields can be used and are all required unless specified otherwise:

EXAMPLES block¶

The EXAMPLES section is required for all new modules.

Examples should demonstrate real world usage, and be written in multi-line plain-text YAML format.

Ensure that examples are kept in sync with the options during the PR review and any following code refactor.

As per playbook best practice, a name: should be specified.

EXAMPLES string within the module like this:

EXAMPLES = '''
- name: Ensure foo is installed
  modulename:
    name: foo
    state: present
'''

If the module returns facts that are often needed, an example of how to use them can be helpful.

RETURN Block¶

The RETURN section documents what the module returns, and is required for all new modules.

For each value returned, provide a description, in what circumstances the value is returned, the type of the value and a sample. For example, from the copy module:

The following fields can be used and are all required unless specified otherwise.

For complex nested returns type can be specified as type: complex.

Example:

RETURN = '''
dest:
    description: destination file/path
    returned: success
    type: string
    sample: /path/to/file.txt
src:
    description: source file used for the copy on the target machine
    returned: changed
    type: string
    sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
md5sum:
    description: md5 checksum of the file after running copy
    returned: when supported
    type: string
    sample: 2a5aeecc61dc98c4d780b14b330e3282
'''

RETURN = '''
packages:
    description: Information about package requirements
    returned: On success
    type: complex
    contains:
        missing:
            description: Packages that are missing from the system
            returned: success
            type: list
            sample:
                - libmysqlclient-dev
                - libxml2-dev
        badversion:
            description: Packages that are installed but at bad versions.
            returned: success
            type: list
            sample:
                - package: libxml2-dev
                  version: 2.9.4+dfsg1-2
                  constraint: ">= 3.0"
'''

Python Imports¶

Starting with Ansible version 2.2, all new modules are required to use imports in the form:

from module_utils.basic import AnsibleModule

Formatting functions¶

These formatting functions are U() for URLs, I() for option names, C() for files and option values and M() for module names. Module names should be specified as M(module) to create a link to the online documentation for that module.

Example usage:

Or if not set the environment variable C(ACME_PASSWORD) will be used.
...
Required if I(state=present)
...
Mutually exclusive with I(project_src) and I(files).
...
See also M(win_copy) or M(win_template).
...
See U(https://www.ansible.com/tower) for an overview.
...
See L(IOS Platform Options guide, ../network/user_guide/platform_ios.html)

Documentation fragments¶

Some categories of modules share common documentation, such as details on how to authenticate options, or file mode settings. Rather than duplicate that information it can be shared using docs_fragments.

These shared fragments are similar to the standard documentation block used in a module, they are just contained in a ModuleDocFragment class.

All the existing docs_fragments can be found in lib/ansible/utils/module_docs_fragments/.

To include, simply add in extends_documentation_fragment: FRAGMENT_NAME into your module.

Examples can be found by searching for extends_documentation_fragment under the Ansible source tree.

Testing documentation¶

The simplest way to check if your documentation works is to use ansible-doc to view it. Any parsing errors will be apparent, and details can be obtained by adding -vvv.

If you are going to submit the module for inclusion in the main Ansible repo you should make sure that it renders correctly as HTML. Put your completed module file into the lib/ansible/modules/$CATEGORY/ directory and then run the command: make webdocs. The new ‘modules.html’ file will be built in the docs/docsite/_build/html/$MODULENAME_module.html directory.

In order to speed up the build process, you can limit the documentation build to only include modules you specify, or no modules at all. To do this, run the command: MODULES=$MODULENAME make webdocs. The MODULES environment variable accepts a comma-separated list of module names. To skip building documentation for all modules, specify a non-existent module name, for example: MODULES=none make webdocs.

You may also build a single page of the entire docsite. From ansible/docs/docsite run make htmlsingle rst=[relative path to the .rst file], for example: make htmlsingle rst=dev_guide/developing_modules_documenting.rst

To test your documentation against your argument_spec you can use validate-modules. Note that this option isn’t currently enabled in Shippable due to the time it takes to run.

# If you don't already, ensure you are using your local checkout
source hacking/env-setup
./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/your/modules/

For more information in testing, including how to add unit and integration tests, see Testing Ansible.