ansible/docs/templates/plugin.rst.j2

.. _@{ module }@:

{% if short_description %}
{% set title = module + ' - ' + short_description|convert_symbols_to_format %}
{% else %}
{% set title = module %}
{% endif %}
{% set title_len = title|length %}

@{ title }@
@{ '+' * title_len }@

{% if version_added is defined and version_added != '' -%}
.. versionadded:: @{ version_added | default('') }@


{% endif %}


.. contents::
   :local:
   :depth: 2

{# ------------------------------------------
 #
 # Please note: this looks like a core dump
 # but it isn't one.
 #
 --------------------------------------------#}
{% if deprecated is defined -%}


DEPRECATED
----------

{# use unknown here? skip the fields? #}
:In: version: @{ deprecated['version'] | default('') | string | convert_symbols_to_format }@
:Why: @{ deprecated['why'] | default('') | convert_symbols_to_format }@
:Alternative: @{ deprecated['alternative'] | default('')|  convert_symbols_to_format }@


{% endif %}

Synopsis
--------

{% if description %}

{% if description is string -%}
* @{ description | convert_symbols_to_format }@
{% else %}
{% for desc in description -%}
* @{ desc | convert_symbols_to_format }@
{% endfor %}
{% endif %}

{% endif %}

{% if aliases is defined -%}

Aliases: @{ ','.join(aliases) }@


{% endif %}

{% if requirements %}
{% set req = 'Requirements' %}
{% if plugin_type == 'module' %}
{% set req = req + ' (on host that executes module)' %}
{% endif %}
{% set req_len = req|length %}
@{ req }@
@{ '-' * req_len }@

{% for req in requirements %}
  * @{ req | convert_symbols_to_format }@
{% endfor %}

{% endif %}

{% if options -%}


Options
-------

.. raw:: html

    <table  border=0 cellpadding=0 class="documentation-table">
        {# Header of the documentation #}
        <tr>
            <th class="head"><div class="cell-border">parameter</div></th>
            <th class="head"><div class="cell-border">required</div></th>
            <th class="head"><div class="cell-border">default</div></th>
            <th class="head"><div class="cell-border">choices</div></th>
            {% if plugin_type != 'module' %}
                <th class="head"><div class="cell-border">configuration</div></th>
            {% endif %}
            <th class="head"><div class="cell-border">comments</div></th>
        </tr>
        {% for key, value in options.items() recursive %}
            <tr class="return-value-column">
                {# parameter name with introduced label #}
                <td>
                    <div class="outer-elbow-container">
                        {% for i in range(1, loop.depth) %}
                            <div class="elbow-placeholder">
                            </div>
                        {% endfor %}
                        <div class="elbow-key">
                            @{ key }@<br/><div style="font-size: small;">{% if value.version_added %} (added in @{value.version_added}@){% endif %}</div>
                        </div>
                    <div class="outer-elbow-container">
                </td>
                {# required #}
                <td><div class="cell-border">{% if value.get('required', False) %}yes{% else %}no{% endif %}</div></td>
                {# default value #}
                <td><div class="cell-border">{% if value.default %}@{ value.default }@{% endif %}</div></td>
                {# choices #}
                <td>
                    <div class="cell-border">
                        {% if value.type == 'bool' %}
                            <ul>
                                <li>yes</li>
                                <li>no</li>
                            </ul>
                        {% else %}
                            {% if value.choices %}
                                <ul>
                                    {% for choice in value.choices %}
                                        <li>@{ choice }@</li>
                                    {% endfor %}
                                </ul>
                            {% endif %}
                        {% endif %}
                    </div>
                </td>
                {# configuration #}
                {% if plugin_type != 'module' %}
                    <td>
                        <div class="cell-border">
                            {% if 'ini' in value %}
                                <div> ini entries:
                                    {% for ini in value.ini %}
                                        <p>[@{ ini.section }@ ]<br>@{ ini.key }@ = @{ value.default | default('VALUE') }@</p>
                                    {% endfor %}
                                </div>
                            {% endif %}
                            {% if 'env' in value %}
                                {% for env in value.env %}
                                    <div>env:@{ env.name }@</div>
                                {% endfor %}
                            {% endif %}
                            {% if 'vars' in value %}
                                {% for myvar in value.vars %}
                                    <div>var: @{ myvar.name }@</div>
                                {% endfor %}
                            {% endif %}
                        </div>
                    </td>
                {% endif %}
                {# description #}
                <td>
                    <div class="cell-border">
                        {% if value.description is string %}
                            <div>@{ value.description | replace('\n', '\n    ') | html_ify }@</div>
                        {% else %}
                            {% for desc in value.description %}
                                <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
                            {% endfor %}
                        {% endif %}
                        {% if 'aliases' in value and value.aliases %}
                            </br><div style="font-size: small;">aliases: @{ value.aliases|join(', ') }@</div>
                        {% endif %}
                    </div>
                </td>
            </tr>
            {% if value.suboptions %}
                {% if value.suboptions.items %}
                    @{ loop(value.suboptions.items()) }@
                {% elif value.suboptions[0].items %}
                    @{ loop(value.suboptions[0].items()) }@
                {% endif %}
            {% endif %}
        {% endfor %}
    </table>
    </br>

{% endif %}
{% if examples or plainexamples -%}


Examples
--------

.. code-block:: yaml

{% for example in examples %}
{% if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %}
@{ example['code'] | escape | indent(4, True) }@
{% endfor %}
{% if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %}
{% endif %}


{% if returndocs -%}


Return Values
-------------

Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this {{plugin_type}}:

.. raw:: html

    <table border=0 cellpadding=0 class="documentation-table">
        <tr>
            <th class="head"><div class="cell-border">name</div></th>
            <th class="head"><div class="cell-border">description</div></th>
            <th class="head"><div class="cell-border">returned</div></th>
            <th class="head"><div class="cell-border">type</div></th>
            <th class="head"><div class="cell-border">sample</div></th>
        </tr>
        {% for key, value in returndocs.items() recursive %}
            <tr class="return-value-column">
                <td>
                    <div class="outer-elbow-container">
                        {% for i in range(1, loop.depth) %}
                            <div class="elbow-placeholder">
                            </div>
                        {% endfor %}
                        <div class="elbow-key">
                            @{ key }@
                        </div>
                    </div>
                </td>
                <td>
                    {% if value.description is string %}
                        <div class="cell-border">@{ value.description | replace('\n', '\n    ') | html_ify }@</div>
                    {% else %}
                    {% for desc in value.description %}
                        <div class="cell-border">@{ desc | replace('\n', '\n    ') | html_ify }@</div>
                    {% endfor %}
                    {% endif %}
                </td>
                <td align=center><div class="cell-border">@{ value.returned }@</div></td>
                <td align=center><div class="cell-border">@{ value.type }@</div></td>
                <td align=center><div class="cell-border">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div></td>
            </tr>
            {# ---------------------------------------------------------
             # sadly we cannot blindly iterate through the child dicts,
             # since in some documentations,
             # lists are used instead of dicts. This handles both types
             # ---------------------------------------------------------#}
            {% if value.contains %}
                {% if value.contains.items %}
                    @{ loop(value.contains.items()) }@
                {% elif value.contains[0].items %}
                    @{ loop(value.contains[0].items()) }@
                {% endif %}
            {% endif %}
        {% endfor %}
    </table>
    </br></br>
{% endif %}


{% if notes -%}


Notes
-----

.. note::
{% for note in notes %}
    - @{ note | convert_symbols_to_format }@
{% endfor %}


{% endif %}
{% if author is defined -%}


Author
~~~~~~

{% for author_name in author %}
    * @{ author_name }@
{% endfor %}


{% endif %}
{% if not deprecated %}
{% set support = { 'core': 'The Ansible Core Team', 'network': 'The Ansible Network Team', 'certified': 'an Ansible Partner', 'community': 'The Ansible Community', 'curated': 'A Third Party'} %}
{% set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that no backward incompatible interface changes will be made'} %}
{% if metadata %}
{% if metadata.status %}


Status
~~~~~~

{% for cur_state in  metadata.status %}
This module is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@.
{% endfor %}


{% endif %}
{% if metadata.supported_by in ('core', 'network') %}


Maintenance Info
~~~~~~~~~~~~~~~~

For more information about Red Hat's support of this @{ plugin_type }@,
please refer to this `knowledge base article <https://access.redhat.com/articles/rhel-top-support-policies>`_

{% endif %}
{% endif %}
{% endif %}

If you want to help with development, please read :doc:`../../community`,
:doc:`../../dev_guide/testing` and {% if plugin_type == 'module' %}:doc:`../../dev_guide/developing_modules`{% else %}:doc:`../../dev_guide/developing_plugins`{% endif %}.