443 lines
18 KiB
Django/Jinja
443 lines
18 KiB
Django/Jinja
: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
|
|
|
|
<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 }@">
|
|
<div class="ansibleOptionAnchor" id="parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
|
|
<b>@{ key }@</b>
|
|
<a class="ansibleOptionLink" href="#parameter-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this option"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">@{ value.type | documented_type }@</span>
|
|
{% if value.get('elements') %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
|
|
{% if value.get('required', False) %} / <span style="color: red">required</span>{% endif %}
|
|
</div>
|
|
{% if value.version_added %}<div style="font-style: italic; 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 style="margin: 0; padding: 0"><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> ←</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 | tojson | 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>
|
|
{% for desc in value.description %}
|
|
<div>@{ desc | replace('\n', '\n ') | html_ify }@</div>
|
|
{% endfor %}
|
|
{% 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|dictsort) }@
|
|
{% elif value.suboptions[0].items %}
|
|
@{ loop(value.suboptions[0]|dictsort) }@
|
|
{% endif %}
|
|
{% endif %}
|
|
{% endfor %}
|
|
</table>
|
|
<br/>
|
|
|
|
{% 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
|
|
|
|
<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 }@">
|
|
<div class="ansibleOptionAnchor" id="return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
|
|
<b>@{ key }@</b>
|
|
<a class="ansibleOptionLink" href="#return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this fact"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">@{ value.type | documented_type }@</span>
|
|
{% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
|
|
</div>
|
|
{% if value.version_added %}<div style="font-style: italic; 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|dictsort) }@
|
|
{% elif value.contains[0].items %}
|
|
@{ loop(value.contains[0]|dictsort) }@
|
|
{% 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"> </td>
|
|
{% endfor %}
|
|
<td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
|
|
<div class="ansibleOptionAnchor" id="return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}"></div>
|
|
<b>@{ key }@</b>
|
|
<a class="ansibleOptionLink" href="#return-{% for part in value.full_key %}@{ part }@{% if not loop.last %}/{% endif %}{% endfor %}" title="Permalink to this return value"></a>
|
|
<div style="font-size: small">
|
|
<span style="color: purple">@{ value.type | documented_type }@</span>
|
|
{% if value.elements %} / <span style="color: purple">elements=@{ value.elements | documented_type }@</span>{% endif %}
|
|
</div>
|
|
{% if value.version_added %}<div style="font-style: italic; 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|dictsort) }@
|
|
{% elif value.contains[0].items %}
|
|
@{ loop(value.contains[0]|dictsort) }@
|
|
{% endif %}
|
|
{% endif %}
|
|
{% endfor %}
|
|
</table>
|
|
<br/><br/>
|
|
|
|
{% 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`_.
|
|
|
|
{% 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 <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%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 }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr>`_ 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 %}
|