path: root/docs/templates/plugin.rst.j2

:source: @{ source }@

{# avoids rST "isn't included in any toctree" errors for module docs #}
{% if plugin_type == 'module' %}
:orphan:
{% endif %}

.. _@{ module }@_@{ plugin_type }@:
{% for alias in aliases %}
.. _@{ alias }@_@{ plugin_type }@:
{% endfor %}

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

@{ title }@
@{ '+' * title|length }@

{% 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? #}
:Removed in Ansible: version: @{ deprecated['removed_in'] | 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 -%}

Requirements
~~~~~~~~~~~~
{%   if plugin_type == 'module' %}
The below requirements are needed on the host that executes this @{ plugin_type }@.
{%   else %}
The below requirements are needed on the local master node that executes this @{ plugin_type }@.
{%   endif %}

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

{% endif %}

{% if options -%}

Parameters
----------

.. raw:: html

    <table  border=0 cellpadding=0 class="documentation-table">
        {# Pre-compute the nesting depth to allocate columns -#}
        @{ to_kludge_ns('maxdepth', 1) -}@
        {% for key, value in options|dictsort recursive -%}
            @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@
            {% if value.suboptions -%}
                {% if value.suboptions.items -%}
                    @{ loop(value.suboptions.items()) -}@
                {% elif value.suboptions[0].items -%}
                    @{ loop(value.suboptions[0].items()) -}@
                {% endif -%}
            {% endif -%}
        {% endfor -%}
        {# Header of the documentation -#}
        <tr>
            <th colspan="@{ from_kludge_ns('maxdepth') }@">Parameter</th>
            <th>Choices/<font color="blue">Defaults</font></th>
            {% if plugin_type != 'module' %}
                <th>Configuration</th>
            {% endif %}
            <th width="100%">Comments</th>
        </tr>
        {% for key, value in options|dictsort recursive %}
            <tr>
                {# indentation based on nesting level #}
                {% for i in range(1, loop.depth) %}
                    <td class="elbow-placeholder"></td>
                {% endfor %}
                {# parameter name with required and/or introduced label #}
                <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                    <b>@{ key }@</b>
                    {% if value.get('type', None) %}<br/><div style="font-size: small; color: red">@{ value.type }@</div>{% endif %}
                    {% if value.get('required', False) %}<br/><div style="font-size: small; color: red">required</div>{% endif %}
                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
                </td>
                {# default / choices #}
                <td>
                    {# Turn boolean values in 'yes' and 'no' values #}
                    {% if value.default is sameas true %}
                        {% set _x = value.update({'default': 'yes'}) %}
                    {% elif value.default is sameas false %}
                        {% set _x = value.update({'default': 'no'}) %}
                    {% endif %}
                    {% if value.type == 'bool' %}
                        {% set _x = value.update({'choices': ['no', 'yes']}) %}
                    {% endif %}
                    {# Show possible choices and highlight details #}
                    {% if value.choices %}
                        <ul><b>Choices:</b>
                            {% for choice in value.choices %}
                                {# Turn boolean values in 'yes' and 'no' values #}
                                {% if choice is sameas true %}
                                    {% set choice = 'yes' %}
                                {% elif choice is sameas false %}
                                    {% set choice = 'no' %}
                                {% endif %}
                                {% if (value.default is not list and value.default == choice) or (value.default is list and choice in value.default) %}
                                    <li><div style="color: blue"><b>@{ choice | escape }@</b>&nbsp;&larr;</div></li>
                                {% else %}
                                    <li>@{ choice | escape }@</li>
                                {% endif %}
                            {% endfor %}
                        </ul>
                    {% endif %}
                    {# Show default value, when multiple choice or no choices #}
                    {% if value.default is defined and value.default not in value.choices %}
                        <b>Default:</b><br/><div style="color: blue">@{ value.default | escape }@</div>
                    {% endif %}
                </td>
                {# configuration #}
                {% if plugin_type != 'module' %}
                    <td>
                        {% 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 %}
                    </td>
                {% endif %}
                {# description #}
                <td>
                    {% 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 %}
                        <div style="font-size: small; color: darkgreen"><br/>aliases: @{ value.aliases|join(', ') }@</div>
                    {% endif %}
                </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 notes -%}

Notes
-----

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

{% endif %}

{% if examples or plainexamples -%}

Examples
--------

.. code-block:: yaml+jinja

{%   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 not returnfacts and returndocs and returndocs.ansible_facts is defined %}
{%   set returnfacts = returndocs.ansible_facts.contains %}
{%   set _x = returndocs.pop('ansible_facts', None) %}
{% endif %}

{% if returnfacts -%}

Returned Facts
--------------
Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.

.. raw:: html

    <table border=0 cellpadding=0 class="documentation-table">
        {# Pre-compute the nesting depth to allocate columns #}
        @{ to_kludge_ns('maxdepth', 1) -}@
        {% for key, value in returnfacts|dictsort recursive %}
            @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@
            {% if value.contains -%}
                {% if value.contains.items -%}
                    @{ loop(value.contains.items()) -}@
                {% elif value.contains[0].items -%}
                    @{ loop(value.contains[0].items()) -}@
                {% endif -%}
            {% endif -%}
        {% endfor -%}
        <tr>
            <th colspan="@{ from_kludge_ns('maxdepth') }@">Fact</th>
            <th>Returned</th>
            <th width="100%">Description</th>
        </tr>
        {% for key, value in returnfacts|dictsort recursive %}
            <tr>
                {% for i in range(1, loop.depth) %}
                    <td class="elbow-placeholder"></td>
                {% endfor %}
                <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@" colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                    <b>@{ key }@</b>
                    <br/><div style="font-size: small; color: red">@{ value.type }@</div>
                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
                </td>
                <td>@{ value.returned | html_ify }@</td>
                <td>
                    {% if value.description is string %}
                        <div>@{ value.description | html_ify }@
                        </div>
                    {% else %}
                        {% for desc in value.description %}
                            <div>@{ desc | html_ify }@
                            </div>
                        {% endfor %}
                    {% endif %}
                    <br/>
                    {% if value.sample is defined and value.sample %}
                        <div style="font-size: smaller"><b>Sample:</b></div>
                        {# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div>
                    {% endif %}
                </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 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">
        @{ to_kludge_ns('maxdepth', 1) -}@
        {% for key, value in returndocs|dictsort recursive -%}
            @{ to_kludge_ns('maxdepth', [loop.depth, from_kludge_ns('maxdepth')] | max) -}@
            {% if value.contains -%}
                {% if value.contains.items -%}
                    @{ loop(value.contains.items()) -}@
                {% elif value.contains[0].items -%}
                    @{ loop(value.contains[0].items()) -}@
                {% endif -%}
            {% endif -%}
        {% endfor -%}
        <tr>
            <th colspan="@{ from_kludge_ns('maxdepth') }@">Key</th>
            <th>Returned</th>
            <th width="100%">Description</th>
        </tr>
        {% for key, value in returndocs|dictsort recursive %}
            <tr>
                {% for i in range(1, loop.depth) %}
                    <td class="elbow-placeholder">&nbsp;</td>
                {% endfor %}
                <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                    <b>@{ key }@</b>
                    <br/><div style="font-size: small; color: red">@{ value.type }@</div>
                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
                </td>
                <td>@{ value.returned | html_ify }@</td>
                <td>
                    {% if value.description is string %}
                        <div>@{ value.description | html_ify |indent(4) | trim}@</div>
                    {% else %}
                        {% for desc in value.description %}
                            <div>@{ desc | html_ify |indent(4) | trim}@</div>
                        {% endfor %}
                    {% endif %}
                    <br/>
                    {% if value.sample is defined and value.sample %}
                        <div style="font-size: smaller"><b>Sample:</b></div>
                        {# TODO: The sample should be escaped, using |escape or |htmlify, but both mess things up beyond repair with dicts #}
                        <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | replace('\n', '\n    ') | html_ify }@</div>
                    {% endif %}
                </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 %}

Status
------
{% 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 %}

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

{%     endif %}

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

Support
~~~~~~~
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 %}

{% else %}

This @{ plugin_type }@ is flagged as **deprecated** and will be removed in version @{ deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@. For more information see `DEPRECATED`_.

{% endif %}

{% if author is defined -%}

Author
~~~~~~

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

{% endif %}

.. hint::
{%   if plugin_type == 'module' %}
    If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A%2Blabel:%20docsite_pr>`_ to improve it.
{% else %}
    If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/plugins/@{ plugin_type }@/@{ source }@>`_ to improve it.
{% endif %}