From 4ff0317f3e38b02ea84a2b10ff2c9bca429d89de Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Sun, 25 Feb 2018 16:40:27 +0100 Subject: [PATCH] Improve module doc parameter list (#36688) This PR includes: - Indentation of Jinja constructs - Put parameter name in bold - Title-case table headers - Show 'required' when parameter is required (not yes/no) - Left-align all values --- docs/templates/plugin.rst.j2 | 99 ++++++++++++++++++------------------ 1 file changed, 49 insertions(+), 50 deletions(-) diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index aae36a2e726..47d7aa02144 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -3,14 +3,13 @@ .. _@{ module }@: {% if short_description %} -{% set title = module + ' - ' + short_description|convert_symbols_to_format %} +{% set title = module + ' - ' + short_description|convert_symbols_to_format %} {% else %} -{% set title = module %} +{% set title = module %} {% endif %} -{% set title_len = title|length %} @{ title }@ -@{ '+' * title_len }@ +@{ '+' * title|length }@ {% if version_added is defined and version_added != '' -%} .. versionadded:: @{ version_added | default('') }@ @@ -48,13 +47,13 @@ Synopsis {% if description %} -{% if description is string -%} +{% if description is string -%} * @{ description | convert_symbols_to_format }@ -{% else %} -{% for desc in description -%} +{% else %} +{% for desc in description -%} * @{ desc | convert_symbols_to_format }@ -{% endfor %} -{% endif %} +{% endfor %} +{% endif %} {% endif %} @@ -66,17 +65,17 @@ Aliases: @{ ','.join(aliases) }@ {% endif %} {% if requirements %} -{% set req = 'Requirements' %} -{% if plugin_type == 'module' %} -{% set req = req + ' (on host that executes module)' %} -{% endif %} -{% set req_len = req|length %} +{% set req = 'Requirements' %} +{% if plugin_type == 'module' %} +{% set req = req + ' (on host that executes module)' %} +{% endif %} +{% set req_len = req|length %} @{ req }@ @{ '-' * req_len }@ -{% for req in requirements %} +{% for req in requirements %} * @{ req | convert_symbols_to_format }@ -{% endfor %} +{% endfor %} {% endif %} @@ -91,14 +90,14 @@ Options {# Header of the documentation #} - - - - + + + + {% if plugin_type != 'module' %} - + {% endif %} - + {% for key, value in options|dictsort recursive %} @@ -110,14 +109,14 @@ Options {% endfor %}
- @{ key }@
{% if value.version_added %} (added in @{value.version_added}@){% endif %}
+ @{ key }@
{% if value.version_added %} (added in @{value.version_added}@){% endif %}
{# required #} -
+ {# default value #} - + {# choices #}
parameter
required
default
choices
Parameter
Required?
Default
Choices
configuration
Configuration
comments
Comments
{% if value.get('required', False) %}required{% else %}optional{% endif %}
{% if value.get('required', False) %}required{% endif %}
{% if value.default %}@{ value.default }@{% endif %}
{% if value.default %}@{ value.default | html_ify }@{% endif %}
@@ -197,11 +196,11 @@ Examples .. code-block:: yaml -{% for example in examples %} -{% if example['description'] %}@{ example['description'] | indent(4, True) }@{% endif %} +{% 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 %} +{% endfor %} +{% if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %} {% endif %} @@ -217,11 +216,11 @@ Common return values are documented :ref:`here `, the foll - - - - - + + + + + {% for key, value in returndocs|dictsort recursive %} @@ -232,7 +231,7 @@ Common return values are documented :ref:`here `, the foll {% endfor %}
- @{ key }@ + @{ key }@
@@ -245,9 +244,9 @@ Common return values are documented :ref:`here `, the foll {% endfor %} {% endif %} - - - + + + {# --------------------------------------------------------- # sadly we cannot blindly iterate through the child dicts, @@ -274,9 +273,9 @@ Notes ----- .. note:: -{% for note in notes %} +{% for note in notes %} - @{ note | convert_symbols_to_format }@ -{% endfor %} +{% endfor %} {% endif %} @@ -286,17 +285,17 @@ Notes Author ~~~~~~ -{% for author_name in author %} +{% for author_name in author %} * @{ author_name }@ -{% endfor %} +{% endfor %} {% 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 %} +{% 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 %} Status @@ -307,8 +306,8 @@ This module is flagged as **@{cur_state}@** which means that @{module_states[cur {% endfor %} -{% endif %} -{% if metadata.supported_by in ('core', 'network') %} +{% endif %} +{% if metadata.supported_by in ('core', 'network') %} Maintenance Info @@ -317,8 +316,8 @@ Maintenance Info For more information about Red Hat's support of this @{ plugin_type }@, please refer to this `Knowledge Base article `_ -{% endif %} -{% endif %} +{% endif %} +{% endif %} {% endif %} If you want to help with development, please read :doc:`../../community/index`,
name
description
returned
type
sample
Name
Description
Returned
Type
Sample
@{ value.returned }@
@{ value.type }@
@{ value.sample | replace('\n', '\n ') | html_ify }@
@{ value.returned }@
@{ value.type }@
@{ value.sample | replace('\n', '\n ') | html_ify }@