mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
baf0ad2309
* Docs: Add a separate "seealso" section to the module docs
to list related modules and/or related references. This clears up the notes
section for things that are actual notes.
So you can add a section in your module documentation and four types of
references are possible.
seealso:
# Reference by module name
- module: aci_tenant
# Reference by module name, including description
- module: aci_tenant
description: ACI module to create tenants on a Cisco ACI fabric.
# Reference by rST documentation anchor
- ref: aci_guide
description: Detailed information on how to manage your ACI infrastructure using Ansible.
# Reference by Internet resource
- name: APIC Management Information Model reference
description: Complete reference of the APIC object model.
link: https://developer.cisco.com/docs/apic-mim-ref/
This PR also includes:
- Implements ansible-doc support
- Implements schema support for the seealso options
- Updates to the development documentation
- Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
- This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
- We fixed the possible suboption types (which was limited to 'bool' only)
* Use latest stable instead of devel docs
467 lines
18 KiB
Django/Jinja
467 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: 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 | rst_ify }@
|
|
:Why: @{ deprecated['why'] | default('') | rst_ify }@
|
|
:Alternative: @{ deprecated['alternative'] | default('') | rst_ify }@
|
|
|
|
|
|
{% endif %}
|
|
|
|
Synopsis
|
|
--------
|
|
{% if description -%}
|
|
|
|
{% if description is string -%}
|
|
- @{ description | rst_ify }@
|
|
{% else %}
|
|
{% for desc in description %}
|
|
- @{ desc | rst_ify }@
|
|
{% 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 | 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>
|
|
{% 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> ←</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 | rst_ify }@
|
|
{% endfor %}
|
|
|
|
{% endif %}
|
|
|
|
{% if seealso -%}
|
|
See Also
|
|
--------
|
|
|
|
.. seealso::
|
|
|
|
{% for item in seealso %}
|
|
{% if item.module is defined and item.description is defined %}
|
|
:ref:`Module @{ item.module }@ <@{ 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>
|
|
<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"> </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 %}
|
|
|
|
Maintenance
|
|
-----------
|
|
|
|
{% set supported_by = support[metadata.supported_by] %}
|
|
This @{ plugin_type }@ is flagged as **@{metadata.supported_by}@** which means that it is maintained by @{ supported_by }@. See :ref:`Module Maintenance & Support <modules_support>` for more info.
|
|
|
|
For a list of other modules that are also maintained by @{ supported_by }@, see :ref:`here <@{ metadata.supported_by }@_supported>`.
|
|
|
|
{% 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 %}
|
|
|
|
{% endif %}
|
|
|
|
{% else %}
|
|
|
|
This @{ plugin_type }@ is flagged as **deprecated** and will be removed in version @{ deprecated['removed_in'] | default('') | string | rst_ify }@. 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 %}
|