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.
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
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.
..code-block:: shell-session
# If you don't already, ensure you are using your local checkout
