Improve module docs return values (#36943)
* Improve module docs return values Currently the 5 columns shown doesn't make optimal use of the screen estate, especially for facts modules this is a problem. * Add returned facts as a separate section * Remove whitespace and add support section Since Notes were moved higher up, the Author, Status and Maintainer information was now placed under the Return Values section. * Switch Last Updated and Copyright
This commit is contained in:
Dag Wieers
John R Barker
parent
7a4e270ae0
commit
eb52a88fb6
2 changed files with 139 additions and 73 deletions
|
|
@ -22,9 +22,7 @@
|
|||
</script>
|
||||
|
||||
<p>
|
||||
{%- if last_updated %}{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>{% endif %}
|
||||
Copyright © 2018 Red Hat, Inc. <br/>
|
||||
{%- if last_updated %}
|
||||
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
|
||||
{%- endif %}
|
||||
</p>
|
||||
</footer>
|
||||
|
|
|
|||
208
docs/templates/plugin.rst.j2
vendored
208
docs/templates/plugin.rst.j2
vendored
|
|
@ -13,11 +13,8 @@
|
|||
|
||||
{% if version_added is defined and version_added != '' -%}
|
||||
.. versionadded:: @{ version_added | default('') }@
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
|
|
@ -33,7 +30,6 @@
|
|||
|
||||
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 }@
|
||||
|
|
@ -44,43 +40,40 @@ DEPRECATED
|
|||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
{% if description %}
|
||||
{% if description -%}
|
||||
|
||||
{% if description is string -%}
|
||||
* @{ description | convert_symbols_to_format }@
|
||||
- @{ description | convert_symbols_to_format }@
|
||||
{% else %}
|
||||
{% for desc in description -%}
|
||||
* @{ desc | convert_symbols_to_format }@
|
||||
{% for desc in description %}
|
||||
- @{ desc | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% if aliases is defined -%}
|
||||
|
||||
Aliases: @{ ','.join(aliases) }@
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% if requirements %}
|
||||
{% set req_title = 'Requirements' %}
|
||||
{% if requirements -%}
|
||||
|
||||
Requirements
|
||||
~~~~~~~~~~~~
|
||||
{% if plugin_type == 'module' %}
|
||||
{% set req_title = req_title + ' (on host that executes 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 %}
|
||||
@{ req_title }@
|
||||
@{ '-' * req_title|length }@
|
||||
|
||||
{% for req in requirements %}
|
||||
* @{ req | convert_symbols_to_format }@
|
||||
- @{ req | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% if options -%}
|
||||
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
|
|
@ -186,8 +179,8 @@ Options
|
|||
</br>
|
||||
|
||||
{% endif %}
|
||||
{% if notes -%}
|
||||
|
||||
{% if notes -%}
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
|
@ -197,10 +190,9 @@ Notes
|
|||
- @{ note | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if examples or plainexamples -%}
|
||||
|
||||
{% if examples or plainexamples -%}
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
|
@ -212,28 +204,29 @@ Examples
|
|||
@{ 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 returndocs -%}
|
||||
{% if returnfacts -%}
|
||||
|
||||
|
||||
Return Values
|
||||
-------------
|
||||
|
||||
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this @{ plugin_type }@:
|
||||
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">
|
||||
<tr>
|
||||
<th class="head"><div class="cell-border">Name</div></th>
|
||||
<th class="head"><div class="cell-border">Description</div></th>
|
||||
<th class="head"><div class="cell-border">Fact</div></th>
|
||||
<th class="head"><div class="cell-border">Returned</div></th>
|
||||
<th class="head"><div class="cell-border">Type</div></th>
|
||||
<th class="head"><div class="cell-border">Sample</div></th>
|
||||
<th class="head"><div class="cell-border">Description</div></th>
|
||||
</tr>
|
||||
{% for key, value in returndocs|dictsort recursive %}
|
||||
{% for key, value in returnfacts|dictsort recursive %}
|
||||
<tr class="return-value-column">
|
||||
<td>
|
||||
<div class="outer-elbow-container">
|
||||
|
|
@ -243,21 +236,28 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
|
|||
{% endfor %}
|
||||
<div class="elbow-key">
|
||||
<b>@{ key }@</b>
|
||||
<br/><div style="font-size: small; color: red">@{ value.type }@</div>
|
||||
</div>
|
||||
</div>
|
||||
</td>
|
||||
<td>
|
||||
{% if value.description is string %}
|
||||
<div class="cell-border">@{ value.description | replace('\n', '\n ') | html_ify }@</div>
|
||||
{% else %}
|
||||
{% for desc in value.description %}
|
||||
<div class="cell-border">@{ desc | replace('\n', '\n ') | html_ify }@</div>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</td>
|
||||
<td><div class="cell-border">@{ value.returned }@</div></td>
|
||||
<td><div class="cell-border">@{ value.type }@</div></td>
|
||||
<td><div class="cell-border">@{ value.sample | replace('\n', '\n ') | html_ify }@</div></td>
|
||||
<td>
|
||||
<div class="cell-border">
|
||||
{% 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 %}
|
||||
<div style="font-size: smaller"><b>Sample:</b></div>
|
||||
{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
{# ---------------------------------------------------------
|
||||
# sadly we cannot blindly iterate through the child dicts,
|
||||
|
|
@ -273,49 +273,117 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
|
|||
{% endif %}
|
||||
{% endfor %}
|
||||
</table>
|
||||
</br></br>
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% if author is defined -%}
|
||||
|
||||
|
||||
Author
|
||||
~~~~~~
|
||||
|
||||
{% for author_name in author %}
|
||||
* @{ author_name }@
|
||||
{% endfor %}
|
||||
|
||||
<br/><br/>
|
||||
|
||||
{% endif %}
|
||||
{% 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 %}
|
||||
|
||||
{% 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">
|
||||
<tr>
|
||||
<th class="head"><div class="cell-border">Key</div></th>
|
||||
<th class="head"><div class="cell-border">Returned</div></th>
|
||||
<th class="head"><div class="cell-border">Description</div></th>
|
||||
</tr>
|
||||
{% for key, value in returndocs|dictsort recursive %}
|
||||
<tr class="return-value-column">
|
||||
<td>
|
||||
<div class="outer-elbow-container">
|
||||
{% for i in range(1, loop.depth) %}
|
||||
<div class="elbow-placeholder">
|
||||
</div>
|
||||
{% endfor %}
|
||||
<div class="elbow-key">
|
||||
<b>@{ key }@</b>
|
||||
<br/><div style="font-size: small; color: red">@{ value.type }@</div>
|
||||
</div>
|
||||
</div>
|
||||
</td>
|
||||
<td><div class="cell-border">@{ value.returned }@</div></td>
|
||||
<td>
|
||||
<div class="cell-border">
|
||||
{% 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 %}
|
||||
<div style="font-size: smaller"><b>Sample:</b></div>
|
||||
{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #}
|
||||
<div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
</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') %}
|
||||
|
||||
|
||||
Maintenance Info
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
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 :ref:`DEPRECATED`.
|
||||
|
||||
{% endif %}
|
||||
|
||||
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+label:%20docsite_pr>`_ to improve it.
|
||||
{% if author is defined -%}
|
||||
|
||||
Author
|
||||
~~~~~~
|
||||
|
||||
{% for author_name in author %}
|
||||
- @{ author_name }@
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
.. hint::
|
||||
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+label:%20docsite_pr>`_ to improve it.
|
||||
|
|
|
|||
Loading…
Reference in a new issue