: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 }@"> <b>@{ key }@</b> <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 }@"> <b>@{ key }@</b> <div style="font-size: small; color: purple">@{ value.type | documented_type }@</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 }@"> <b>@{ key }@</b> <div style="font-size: small; color: purple">@{ value.type | documented_type }@</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`_. {% 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 }@ <modules_support>`. *[@{ 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 <https://access.redhat.com/articles/3166901>`_. {% 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 <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 %}