The online module documentation is generated from the modules themselves.
As the module documentation is generated from documentation strings contained in the modules, all modules included with Ansible must have a ``DOCUMENTATION`` string.
See an example documentation string in the checkout under `examples/DOCUMENTATION.yml <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_.
Include it in your module file like this:
..code-block:: python
#!/usr/bin/python
# Copyright header....
DOCUMENTATION = '''
---
module: modulename
short_description: This is a sentence describing the module
The following fields can be used and are all required unless specified otherwise:
*``module:``
The name of the module. This must be the same as the filename, without the ``.py`` extension.
*``short_description:``
* A short description which is displayed on the :doc:`../list_of_all_modules` page and ``ansible-doc -l``.
* As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
* Unlike ``description:`` this field should not have a trailing full stop.
*``description:``
* A detailed description (generally two or more sentences).
* Must be written in full sentences, i.e. with capital letters and fullstops.
* Shouldn't mention the name module.
*``version_added:``
The version of Ansible when the module was added.
This is a `string`, and not a float, i.e. ``version_added: "2.1"``
*``author:``
Name of the module author in the form ``First Last (@GitHubID)``. Use a multi-line list if there is more than one author.
*``options:``
One per module argument
*``description:``
* Detailed explanation of what this option does. It should be written in full sentences.
* Should not list the options values (that's what ``choices:`` is for, though it should explain `what` the values do if they aren't obvious.
* If an argument takes both True)/False and Yes)/No, the documentation should use True and False.
* If an optional parameter is sometimes required this need to be reflected in the documentation, e.g. "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, otherwise it is assumed to be false.
*``default:``
* If `required` is false/missing, `default` may be specified (assumed 'null' if missing).
* Ensure that the default parameter in the docs matches the default parameter in the code.
* The default option must not be listed as part of the description.
*``choices:``
List of option values. Should be absent if empty.
*``aliases:``
List of option name aliases; generally not needed.
*``version_added:``
Only needed if this option was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
This is a string, and not a float, i.e. ``version_added: "2.3"``.
*``requirements:``
List of requirements, and minimum versions (if applicable)
*``notes:``
Details of any important information that doesn't fit in one of the above sections; for example if ``check_mode`` isn't supported, or a link to external documentation.
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.
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.
..note::
If you wish to refer a collection of modules, use ``C(..)``, e.g. ``Refer to the C(win_*) modules.``
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
'''''''''''''''''''''
Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` directory and then
