Module format and documentation

Documentation fields

All fields in the DOCUMENTATION block are lower-case. All fields are required unless specified otherwise:

module:

• The name of the module.

• Must be the same as the file name, without the .py extension.

short_description:

• A short description which is displayed on the Collection Index page and ansible-doc -l.

• The short_description is displayed by ansible-doc -l without any category grouping, so it needs enough detail to explain the module’s purpose without the context of the directory structure in which it lives.

• Unlike description:, short_description should not have a trailing period/full stop.

description:

• A detailed description (generally two or more sentences).

• Must be written in full sentences, in other words, with capital letters and periods/full stops.

• Shouldn’t mention the module name.

• Make use of multiple entries rather than using one long paragraph.

• Don’t quote complete values unless it is required by YAML.

version_added:

• The version of Ansible when the module was added.

• This is a string, and not a float, for example, version_added: '2.1'.

• In collections, this must be the collection version the module was added to, not the Ansible version. For example, version_added: 1.0.0.

author:

• Name of the module author in the form First Last (@GitHubID).

• Use a multi-line list if there is more than one author.

• Don’t use quotes as it should not be required by YAML.

deprecated:

• Marks modules that will be removed in future releases. See also The lifecycle of an Ansible module or plugin.

options:

• Options are often called “parameters” or “arguments”. Because the documentation field is called options, we will use that term.

• If the module has no options (for example, it is a _facts module), all you need is one line: options: {}.

• If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module option, include:

option-name:

• Declarative operation (not CRUD), to focus on the final state, for example online:, rather than is_online:.

• The name of the option should be consistent with the rest of the module, as well as other modules in the same category.

• When in doubt, look for other modules to find option names that are used for the same purpose, we like to offer consistency to our users.

• (There is no explicit field option-name. This entry is about the key of the option in the options dictionary.)

description:

• Detailed explanation of what this option does. It should be written in full sentences.

• The first entry is a description of the option itself; subsequent entries detail its use, dependencies, or format of possible values.

• Should not list the possible values (that’s what choices: is for, though it should explain what the values do if they aren’t obvious).

• If an option is only sometimes required, describe the conditions. For example, “Required when I(state=present).”

• Mutually exclusive options must be documented as the final sentence on each of the options.

required:

• Only needed if true.

• If missing, we assume the option is not required.

default:

• If required is false/missing, default may be specified (assumed ‘null’ if missing).

• Ensure that the default value in the docs matches the default value in the code.

• The default field must not be listed as part of the description, unless it requires additional information or conditions.

• If the option is a boolean value, you can use any of the boolean values recognized by Ansible (such as true/false or yes/no). Document booleans as true/false for consistency and compatibility with ansible-lint.

choices:

• List of option values.

• Should be absent if empty.

type:

• Specifies the data type that option accepts, must match the argspec.

• If an argument is type='bool', this field should be set to type: bool and no choices should be specified.

• If an argument is type='list', elements should be specified.

elements:

• Specifies the data type for list elements in case type='list'.

aliases:

• List of optional name aliases.

• Generally not needed.

version_added:

• Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level version_added field.

• This is a string, and not a float, for example, version_added: '2.3'.

• In collections, this must be the collection version the option was added to, not the Ansible version. For example, version_added: 1.0.0.

suboptions:

• If this option takes a dict or list of dicts, you can define the structure here.

• See azure.azcollection.azure_rm_securitygroup, azure.azcollection.azure_rm_azurefirewall, and openstack.cloud.baremetal_node_action for examples.

requirements:

• List of requirements (if applicable).

• Include minimum versions.

seealso:

• A list of references to other modules, documentation or Internet resources

• In Ansible 2.10 and later, references to modules must use the FQCN or ansible.builtin for modules in ansible-core.

• Plugin references are supported since ansible-core 2.15.

• A reference can be one of the following formats:

  seealso:
  
  # Reference by module name
  - module: cisco.aci.aci_tenant
  
  # Reference by module name, including description
  - module: cisco.aci.aci_tenant
    description: ACI module to create tenants on a Cisco ACI fabric.
  
  # Reference by plugin name
  - plugin: ansible.builtin.file
    plugin_type: lookup
  
  # Reference by plugin name, including description
  - plugin: ansible.builtin.file
    plugin_type: lookup
    description: You can use the ansible.builtin.file lookup to read files on the control node.
  
  # Reference by rST documentation anchor
  - ref: aci_guide
    description: Detailed information on how to manage your ACI infrastructure using Ansible.
  
  # Reference by rST documentation anchor (with custom title)
  - ref: The official Ansible ACI guide <aci_guide>
    description: Detailed information on how to manage your ACI infrastructure using Ansible.
  
  # Reference by Internet resource
  - name: APIC Management Information Model reference
    description: Complete reference of the APIC object model.
    link: https://developer.cisco.com/docs/apic-mim-ref/
  

• If you use ref: to link to an anchor that is not associated with a title, you must add a title to the ref for the link to work correctly.

attributes:

• A dictionary mapping attribute names to dictionaries describing that attribute.

• Usually attributes are provided by documentation fragments, for example ansible.builtin.action_common_attributes and its sub-fragments. Modules and plugins use the appropriate docs fragments and fill in the support, details, and potential attribute-specific other fields.

description:

• A string or a list of strings. Each string is one paragraph. The description is required.

• Explanation of what this attribute does. It should be written in full sentences.

details:

• A string or a list of strings. Each string is one paragraph.

• Describes how support might not work as expected by the user.

• The details are optional in general, but must be provided if support is partial.

support:

• One of full, none, partial, or N/A. This is required.

• Indicates whether this attribute is supported by this module or plugin.

membership:

• A string or a list of strings.

• Must only be used for the attribute action_group, and must always be specified for that attribute.

• Lists the action groups this module or action is part of.

platforms:

• A string or a list of strings.

• Must only be used for the attribute platform, and must always be specified for that attribute.

• Lists the platforms the module or action supports.

version_added:

• Only needed if this attribute’s support was extended after the module/plugin was created, in other words, this is greater than the top level version_added field.

• This is a string, and not a float, for example, version_added: '2.3'.

• In collections, this must be the collection version the attribute’s support was added to, not the Ansible version. For example, version_added: 1.0.0.

notes:

• Details of any important information that doesn’t fit in one of the above sections.

• Information on check_mode or diff should not be listed here, but instead be mentioned in the attributes.

Linking within module documentation

You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:

• L() for links with a heading. For example: See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform). As of Ansible 2.10, do not use L() for relative links between Ansible documentation and collection documentation.

• U() for URLs. For example: See U(https://www.ansible.com/products/automation-platform) for an overview.

• R() for cross-references with a heading (added in Ansible 2.10). For example: See R(Cisco IOS Platform Guide,ios_platform_options). Use the RST anchor for the cross-reference. See Adding anchors for details.

• M() for module names. For example: See also M(ansible.builtin.yum) or M(community.general.apt_rpm). A FQCN must be used, short names will create broken links; use ansible.builtin for modules in ansible-core.

• P() for plugin names. For example: See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter). This can also reference roles: P(community.sops.install#role). This is supported since ansible-core 2.15. FQCNs must be used; use ansible.builtin for plugins in ansible-core.

Semantic markup within module documentation

You can use semantic markup to highlight option names, option values, and environment variables. The markup processor formats these highlighted terms in a uniform way. With semantic markup, we can modify how the output looks without changing underlying code.

The correct formats for semantic markup are as follows:

• O() for option names, whether mentioned alone or with values. For example: Required if O(state=present). and Use with O(force) to require secure access.

• V() for option values when mentioned alone. For example: Possible values include V(monospace) and V(pretty).

• RV() for return value names, whether mentioned alone or with values. For example: The module returns RV(changed=true) in case of changes. and Use the RV(stdout) return value for standard output.

• E() for environment variables. For example: If not set, the environment variable E(ACME_PASSWORD) will be used.

The parameters for these formatting functions can use escaping with backslashes: V(foo(bar="a\\b"\), baz) results in the formatted value foo(bar="a\b"), baz).

Rules for using O() and RV() are very strict. You must follow syntax rules so that documentation renderers can create hyperlinks for the options and return values, respectively.

The allowed syntaxes are as follows:

• To reference an option for the current plugin/module, or the entrypoint of the current role (inside role entrypoint documentation), use O(option) and O(option=name).

• To reference an option for another entrypoint entrypoint from inside role documentation, use O(entrypoint:option) and O(entrypoint:option=name). The entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint.

• To reference an option for another plugin/module plugin.fqcn.name of type type, use O(plugin.fqcn.name#type:option) and O(plugin.fqcn.name#type:option=name). For modules, use type=module. The FQCN and plugin type can be ignored by the documentation renderer, turned into a link to that plugin, or even directly to the option of that plugin.

• To reference an option for entrypoint entrypoint of another role role.fqcn.name, use O(role.fqcn.name#role:entrypoint:option) and O(role.fqcn.name#role:entrypoint:option=name). The FQCN and entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint.

• To reference options that do not exist (for example, options that were removed in an earlier version), use O(ignore:option) and O(ignore:option=name). The ignore: part will not be shown to the user by documentation rendering.

Option names can refer to suboptions by listing the path to the option separated by dots. For example, if you have an option foo with suboption bar, then you must use O(foo.bar) to reference that suboption. You can add array indications like O(foo[].bar) or even O(foo[-1].bar) to indicate specific list elements. Everything between [ and ] pairs will be ignored to determine the real name of the option. For example, O(foo[foo | length - 1].bar[]) results in the same link as O(foo.bar), but the text foo[foo | length - 1].bar[] displays instead of foo.bar.

The same syntaxes can be used for RV(), except that these will refer to return value names instead of option names; for example RV(ansible.builtin.service_facts#module:ansible_facts.services) refers to the ansible_facts.services fact returned by the ansible.builtin.service_facts module.

Format macros within module documentation

While it is possible to use standard Ansible formatting macros to control the look of other terms in module documentation, you should do so sparingly.

Possible macros include the following:

• C() for monospace (code) text. For example: This module functions like the unix command C(foo).

• B() for bold text.

• I() for italic text.

• HORIZONTALLINE for a horizontal rule (the <hr> html tag) to separate long descriptions.

Note that C(), B(), and I() do not allow escaping, and thus cannot contain the value ) as it always ends the formatting sequence. If you need to use ) inside C(), we recommend to use V() instead; see the above section on semantic markup.

Documentation fragments

If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, notes: or seealso: entries. Rather than duplicate that information in each module’s DOCUMENTATION block, you can save it once as a doc_fragment plugin and use it in each module’s documentation. In Ansible, shared documentation fragments are contained in a ModuleDocFragment class in lib/ansible/plugins/doc_fragments/ or the equivalent directory in a collection. To include a documentation fragment, add extends_documentation_fragment: FRAGMENT_NAME in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, kubernetes.core.k8s_auth_options).

Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment.

By default, only the DOCUMENTATION property from a doc fragment is inserted into the module documentation. It is possible to define additional properties in the doc fragment in order to import only certain parts of a doc fragment or mix and match as appropriate. If a property is defined in both the doc fragment and the module, the module value overrides the doc fragment.

Here is an example doc fragment named example_fragment.py:

class ModuleDocFragment(object):
    # Standard documentation
    DOCUMENTATION = r'''
    options:
      # options here
    '''

    # Additional section
    OTHER = r'''
    options:
      # other options here
    '''

To insert the contents of OTHER in a module:

extends_documentation_fragment: example_fragment.other

Or use both :

extends_documentation_fragment:
  - example_fragment
  - example_fragment.other

Since Ansible 2.8, you can have user-supplied doc_fragments by using a doc_fragments directory adjacent to play or role, just like any other plugin.

For example, all AWS modules should include:

extends_documentation_fragment:
- aws
- ec2

Using documentation fragments in collections describes how to incorporate documentation fragments in a collection.