mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
fa5c0282a4
Address Firefox table-rendering issues in docs. Refactor to use colspan to provide table cells which can vary in width and indentation; the outermost has the greatest colspan, and each nested key has a colspan of one less than the parent, with padding cells for indentation. Apply styling to table cells to get the table height to work without hacks or browser-specific styling. Simplify the markup and CSS by removing extra divs. Use two passes over the options, return values, and return facts in the Jinja2 module-docs template: one to determine the maximum nesting depth to compute the maximum colspan needed, plus one to lay out the rows.
428 lines
16 KiB
Django/Jinja
428 lines
16 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|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 #}
|
|
{% set ns = namespace(maxdepth=1) %}
|
|
{% for key, value in options|dictsort recursive %}
|
|
{% set ns.maxdepth = [loop.depth, 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="@{ 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="@{ ns.maxdepth - loop.depth0 }@">
|
|
<b>@{ key }@</b>
|
|
{% 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 string and value.default == choice) or (value.default is iterable and value.default is not string 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 | convert_symbols_to_format }@
|
|
{% endfor %}
|
|
|
|
{% endif %}
|
|
|
|
{% if examples or plainexamples -%}
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. code-block:: yaml
|
|
|
|
{% 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 #}
|
|
{% set ns = namespace(maxdepth=1) %}
|
|
{% for key, value in returnfacts|dictsort recursive %}
|
|
{% set ns.maxdepth = [loop.depth, 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="@{ 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="@{ ns.maxdepth - loop.depth0 }@" colspan="@{ ns.maxdepth - loop.depth0 }@">
|
|
<b>@{ key }@</b>
|
|
<br/><div style="font-size: small; color: red">@{ value.type }@</div>
|
|
</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">
|
|
{% set ns = namespace(maxdepth=1) %}
|
|
{% for key, value in returndocs|dictsort recursive %}
|
|
{% set ns.maxdepth = [loop.depth, 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="@{ 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="@{ ns.maxdepth - loop.depth0 }@">
|
|
<b>@{ key }@</b>
|
|
<br/><div style="font-size: small; color: red">@{ value.type }@</div>
|
|
</td>
|
|
<td>@{ value.returned | html_ify }@</td>
|
|
<td>
|
|
{% if value.description is string %}
|
|
<div>@{ value.description | html_ify |indent(4)}@</div>
|
|
{% else %}
|
|
{% for desc in value.description %}
|
|
<div>@{ desc | html_ify |indent(4)}@</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 module 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 module 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 %}
|