: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 | rst_ify %} {% else %} {% set title = module %} {% endif %} @{ title }@ @{ '+' * title|length }@ {% if version_added is defined and version_added != '' -%} .. versionadded:: @{ version_added | default('') }@ {% endif %} .. contents:: :local: :depth: 1 {# ------------------------------------------ # # 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 | rst_ify }@ :Why: @{ deprecated['why'] | default('') | rst_ify }@ :Alternative: @{ deprecated['alternative'] | default('') | rst_ify }@ {% endif %} Synopsis -------- {% if description -%} {% for desc in description %} - @{ desc | rst_ify }@ {% endfor %} {% 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 | rst_ify }@ {% endfor %} {% endif %} {% if options -%} Parameters ---------- .. raw:: html {# 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 -#} {% if plugin_type != 'module' %} {% endif %} {% for key, value in options|dictsort recursive %} {# indentation based on nesting level #} {% for i in range(1, loop.depth) %} {% endfor %} {# parameter name with required and/or introduced label #} {# default / choices #} {# configuration #} {% if plugin_type != 'module' %} {% endif %} {# description #} {% if value.suboptions %} {% if value.suboptions.items %} @{ loop(value.suboptions|dictsort) }@ {% elif value.suboptions[0].items %} @{ loop(value.suboptions[0]|dictsort) }@ {% endif %} {% endif %} {% endfor %}
Parameter Choices/DefaultsConfigurationComments
@{ key }@
@{ value.type | documented_type }@ {% if value.get('elements') %} / elements=@{ value.elements | documented_type }@{% endif %} {% if value.get('required', False) %} / required{% endif %}
{% if value.version_added %}
added in @{value.version_added}@
{% endif %}
{# 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 %}
    Choices: {% 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) %}
  • @{ choice | escape }@ ←
  • {% else %}
  • @{ choice | escape }@
  • {% endif %} {% endfor %}
{% endif %} {# Show default value, when multiple choice or no choices #} {% if value.default is defined and value.default not in value.choices %} Default:
@{ value.default | tojson | escape }@
{% endif %}
{% if 'ini' in value %}
ini entries: {% for ini in value.ini %}

[@{ ini.section }@]
@{ ini.key }@ = @{ value.default | default('VALUE') }@

{% endfor %}
{% endif %} {% if 'env' in value %} {% for env in value.env %}
env:@{ env.name }@
{% endfor %} {% endif %} {% if 'vars' in value %} {% for myvar in value.vars %}
var: @{ myvar.name }@
{% endfor %} {% endif %}
{% for desc in value.description %}
@{ desc | replace('\n', '\n ') | html_ify }@
{% endfor %} {% if 'aliases' in value and value.aliases %}

aliases: @{ value.aliases|join(', ') }@
{% endif %}

{% endif %} {% if notes -%} Notes ----- .. note:: {% for note in notes %} - @{ note | rst_ify }@ {% endfor %} {% endif %} {% if seealso -%} See Also -------- .. seealso:: {% for item in seealso %} {% if item.module is defined and item.description is defined %} :ref:`@{ item.module }@_module` @{ item.description | rst_ify }@ {% elif item.module is defined %} :ref:`@{ item.module }@_module` The official documentation on the **@{ item.module }@** module. {% elif item.name is defined and item.link is defined and item.description is defined %} `@{ item.name }@ <@{ item.link }@>`_ @{ item.description | rst_ify }@ {% elif item.ref is defined and item.description is defined %} :ref:`@{ item.ref }@` @{ item.description | rst_ify }@ {% endif %} {% 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 {# 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 -%} {% for key, value in returnfacts|dictsort recursive %} {% for i in range(1, loop.depth) %} {% endfor %} {# --------------------------------------------------------- # 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|dictsort) }@ {% elif value.contains[0].items %} @{ loop(value.contains[0]|dictsort) }@ {% endif %} {% endif %} {% endfor %}
Fact Returned Description
@{ key }@
@{ value.type | documented_type }@ {% if value.elements %} / elements=@{ value.elements | documented_type }@{% endif %}
{% if value.version_added %}
added in @{value.version_added}@
{% endif %}
@{ value.returned | html_ify }@ {% if value.description is string %}
@{ value.description | html_ify }@
{% else %} {% for desc in value.description %}
@{ desc | html_ify }@
{% endfor %} {% endif %}
{% if value.sample is defined and value.sample %}
Sample:
{# TODO: The sample should be escaped, using | escape or | htmlify, but both mess things up beyond repair with dicts #}
@{ value.sample | replace('\n', '\n ') | html_ify }@
{% endif %}


{% endif %} {% if returndocs -%} Return Values ------------- Common return values are documented :ref:`here `, the following are the fields unique to this @{ plugin_type }@: .. raw:: html @{ 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 -%} {% for key, value in returndocs|dictsort recursive %} {% for i in range(1, loop.depth) %} {% endfor %} {# --------------------------------------------------------- # 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|dictsort) }@ {% elif value.contains[0].items %} @{ loop(value.contains[0]|dictsort) }@ {% endif %} {% endif %} {% endfor %}
Key Returned Description
  @{ key }@
@{ value.type | documented_type }@ {% if value.elements %} / elements=@{ value.elements | documented_type }@{% endif %}
{% if value.version_added %}
added in @{value.version_added}@
{% endif %}
@{ value.returned | html_ify }@ {% if value.description is string %}
@{ value.description | html_ify |indent(4) | trim}@
{% else %} {% for desc in value.description %}
@{ desc | html_ify |indent(4) | trim}@
{% endfor %} {% endif %}
{% if value.sample is defined and value.sample %}
Sample:
{# TODO: The sample should be escaped, using |escape or |htmlify, but both mess things up beyond repair with dicts #}
@{ value.sample | replace('\n', '\n ') | html_ify }@
{% endif %}


{% endif %} Status ------ {% if deprecated %} - This @{ plugin_type }@ will be removed in version @{ deprecated['removed_in'] | default('') | string | rst_ify }@. *[deprecated]* - For more information see `DEPRECATED`_. {% else %} {% 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': 'not guaranteed to have a backwards compatible interface', 'stableinterface': 'guaranteed to have backward compatible interface changes going forward'} %} {% if metadata %} {% if metadata.status %} {% for cur_state in metadata.status %} - This @{ plugin_type }@ is @{ module_states[cur_state] }@. *[@{ cur_state }@]* {% endfor %} {% endif %} {% if metadata.supported_by %} {% set supported_by = support[metadata.supported_by] %} - This @{ plugin_type }@ is :ref:`maintained by @{ supported_by }@ `. *[@{ metadata.supported_by }@]* {% if metadata.supported_by in ('core', 'network') %} Red Hat Support ~~~~~~~~~~~~~~~ More information about Red Hat's support of this @{ plugin_type }@ is available from this `Red Hat Knowledge Base article `_. {% endif %} {% endif %} {% endif %} {% endif %} {% if author is defined -%} Authors ~~~~~~~ {% 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 `_ to improve it. {% else %} If you notice any issues in this documentation, you can `edit this document `_ to improve it. .. hint:: Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. {% endif %}