<commit_before>.. _module_documenting:

Documenting Your Module
=======================

.. contents:: Topics

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.
This string must be a valid YAML document
which conforms to the schema defined below. You may find it easier to
start writing your ``DOCUMENTATION`` string in an editor with YAML
syntax highlighting before you include it in your Python file.

All modules must have the following sections defined in this order:

1. ANSIBLE_METADATA
2. DOCUMENTATION
3. EXAMPLES
4. RETURNS
5. Python imports

.. note:: Why don't the imports go first?

  Keen Python programmers may notice that contrary to PEP8's advice we don't put ``imports`` at the top of the file. This is because the ``ANSIBLE_METADATA`` through ``RETURNS`` sections are not used by the module code itself; they are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP8 is about). Documentation strings in a module are much more similar to module level docstrings, than code, and are never utilized by the module itself. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.

.. warning:: Why do some modules have imports at the bottom of the file?

  If you look at some existing older modules, you may find imports at the bottom of the file. Do not copy that idiom into new modules as it is a historical oddity due to how modules used to be combined with libraries. Over time we're moving the imports to be in their proper place.



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 = {'status': ['preview'],
                       'supported_by': 'community',
                       'version': '1.0'}

.. warning:: version field

   This is the version of the ``ANSIBLE_METADATA`` schema, *not* the version of the module.

.. warning::

   Promoting a module's ``status`` or ``supported_by`` status should only be done by members of the Ansible Core Team.

Version 1.0 of the metadata
+++++++++++++++++++++++++++

Structure
`````````

Format::

  ANSIBLE_METADATA = {
      'version': '1.0',
      'supported_by': 'core|community|core_curated',
      'status': ['stableinterface|preview|deprecated|removed']
  }

Fields
``````

:version: An “X.Y” formatted string. X and Y are integers which
   define the metadata format version. Modules shipped with Ansible are
   tied to an Ansible release, so we will only ship with a single version
   of the metadata. We’ll increment Y if we add fields or legal values
   to an existing field. We’ll increment X if we remove fields or values
   or change the type or meaning of a field.
:supported_by: This field records who supports the module.
   Default value is community. Values are:

   :core: Maintained by the Ansible core team. Core team will fix
      bugs, add new features, and review PRs.
   :community: This module is maintained by the community at large,
      which is responsible for fixing bugs, adding new features, and
      reviewing changes.
   :unmaintained: This module currently needs a new community
      contributor to help maintain it.
   :committer: Committers to the Ansible repository are the
      gatekeepers for this module. They will review PRs from the community
      before merging but might not generate fixes and code for new features
      on their own.

:status: This field records information about the module that is
   important to the end user. It’s a list of strings. The default value
   is a single element list [“preview”]. The following strings are valid
   statuses and have the following meanings:<commit_msg>Make the metadata docs agree with what's currently implemented<commit_after>.. _module_documenting:

Documenting Your Module
=======================

.. contents:: Topics

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.
This string must be a valid YAML document
which conforms to the schema defined below. You may find it easier to
start writing your ``DOCUMENTATION`` string in an editor with YAML
syntax highlighting before you include it in your Python file.

All modules must have the following sections defined in this order:

1. ANSIBLE_METADATA
2. DOCUMENTATION
3. EXAMPLES
4. RETURNS
5. Python imports

.. note:: Why don't the imports go first?

  Keen Python programmers may notice that contrary to PEP8's advice we don't put ``imports`` at the top of the file. This is because the ``ANSIBLE_METADATA`` through ``RETURNS`` sections are not used by the module code itself; they are essentially extra docstrings for the file. The imports are placed after these special variables for the same reason as PEP8 puts the imports after the introductory comments and docstrings. This keeps the active parts of the code together and the pieces which are purely informational apart. The decision to exclude E402 is based on readability (which is what PEP8 is about). Documentation strings in a module are much more similar to module level docstrings, than code, and are never utilized by the module itself. Placing the imports below this documentation and closer to the code, consolidates and groups all related code in a congruent manner to improve readability, debugging and understanding.

.. warning:: Why do some modules have imports at the bottom of the file?

  If you look at some existing older modules, you may find imports at the bottom of the file. Do not copy that idiom into new modules as it is a historical oddity due to how modules used to be combined with libraries. Over time we're moving the imports to be in their proper place.



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 = {'status': ['preview'],
                       'supported_by': 'community',
                       'version': '1.0'}

.. warning:: version field

   This is the version of the ``ANSIBLE_METADATA`` schema, *not* the version of the module.

.. warning::

   Promoting a module's ``status`` or ``supported_by`` status should only be done by members of the Ansible Core Team.

Version 1.0 of the metadata
+++++++++++++++++++++++++++

Structure
`````````

Format::

  ANSIBLE_METADATA = {
      'version': '1.0',
      'supported_by': 'core|community|unmaintained|committer',
      'status': ['stableinterface|preview|deprecated|removed']
  }

Fields
``````

:version: An “X.Y” formatted string. X and Y are integers which
   define the metadata format version. Modules shipped with Ansible are
   tied to an Ansible release, so we will only ship with a single version
   of the metadata. We’ll increment Y if we add fields or legal values
   to an existing field. We’ll increment X if we remove fields or values
   or change the type or meaning of a field.
:supported_by: This field records who supports the module.
   Default value is community. Values are:

   :core: Maintained by the Ansible core team. Core team will fix
      bugs, add new features, and review PRs.
   :community: This module is maintained by the community at large,
      which is responsible for fixing bugs, adding new features, and
      reviewing changes.
   :unmaintained: This module currently needs a new community
      contributor to help maintain it.
   :committer: Committers to the Ansible repository are the
      gatekeepers for this module. They will review PRs from the community
      before merging but might not generate fixes and code for new features
      on their own.

:status: This field records information about the module that is
   important to the end user. It’s a list of strings. The default value
   is a single element list [“preview”]. The following strings are valid
   statuses and have the following meanings:
{'fraction_non_alphanumeric': 0.06546500055291386, 'fraction_numerical': 0.0037598142209443767, 'mean_word_length': 3.838951310861423, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4331396', 'n_tokens_mistral': 2301, 'n_tokens_neox': 2159, 'n_words': 1309}