From b900f4a3be8f92c5ba8172868f8112e47e179c06 Mon Sep 17 00:00:00 2001 From: Andreas Maier Date: Fri, 18 Aug 2017 21:38:55 +0200 Subject: [PATCH] Fixed return table in module docs generated by plugin_formatter.py (#25329) (#25330) This change fixes two issues with the generated return table: 1. When specifying a list of strings in the 'description' field of a return value, it shows them in Python list syntax on the resulting web page, e.g. `['a', 'b', 'c']`. 2. When specifying more than one line for the 'sample' field, the result table gets damaged in the HTML output. In addition, this change re-arranges the HTML tags produced in the generated RST file such that they line up nicely and can better be checked by humans for completeness. Signed-off-by: Andreas Maier --- docs/templates/plugin.rst.j2 | 187 +++++++++++++++++++++++------------ 1 file changed, 123 insertions(+), 64 deletions(-) diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index 50ee62196e1..34c9c2b1bda 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -61,6 +61,7 @@ Options .. raw:: html + @@ -68,57 +69,94 @@ Options - {% for k in option_keys %} - {% set v = options[k] %} - {% if not v['suboptions'] %} - - - - {% if v.get('type', 'not_bool') == 'bool' %} +{% for k in option_keys -%} +{% set v = options[k] -%} +{% if not v['suboptions'] %} + + + + + +{% if v.get('type', 'not_bool') == 'bool' %} - {% else %} - - {% endif %} - - - - +{% endif %} + + + + + + + +{% endif %} + + +{% endfor %} + +
parameter requiredchoices comments
@{ k }@
{% if v['version_added'] %} (added in @{v['version_added']}@){% endif %}
{% if v.get('required', False) %}yes{% else %}no{% endif %}{% if v['default'] %}@{ v['default'] }@{% endif %}
@{ k }@
{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}
{% if v.get('required', False) -%}yes{% else %}no{% endif -%}{% if v['default'] -%}@{ v['default'] }@{% endif -%}
  • yes
  • no
{% if v['choices'] %}
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% endif %}		{% for desc in v.description -%}
@{ desc | replace('\n', '\n ') | html_ify }@
{% endfor -%} {% if 'aliases' in v and v.aliases -%}
-
aliases: @{ v.aliases|join(', ') }@
{%- endif %} - {% else %} -
@{ k }@
{% if v['version_added'] %} (added in @{v['version_added']}@){% endif %}
{% if v.get('required', False) %}yes{% else %}no{% endif %} {% for desc in v.description -%}
@{ desc | replace('\n', '\n ') | html_ify }@
{% endfor -%} {% if 'aliases' in v and v.aliases -%}
-
aliases: @{ v.aliases|join(', ') }@
{%- endif %} +{% else %} +
{% if v['choices'] -%}
    {% for choice in v.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% endif -%}		 +{% if v.description is string %} +
@{ v.description | replace('\n', '\n ') | html_ify }@
+{% else %} +{% for desc in v.description %} +
@{ desc | replace('\n', '\n ') | html_ify }@
+{% endfor %} +{% endif %} +{% if 'aliases' in v and v.aliases %} +
aliases: @{ v.aliases|join(', ') }@
+{% endif %} +{% else %} + +
@{ k }@
{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}
{% if v.get('required', False) -%}yes{% else -%}no{% endif -%} +{% for desc in v.description %} +
@{ desc | replace('\n', '\n ') | html_ify }@
+{% endfor %} +{% if 'aliases' in v and v.aliases %} +
aliases: @{ v.aliases|join(', ') }@
+{% endif %}
- - - - - - - - - - {% for k2 in v['suboptions'] %} - {% set v2 = v['suboptions'] [k2] %} - - - - {% if v2.get('type', 'not_bool') == 'bool' %} +
Dictionary object @{ k }@
parameterrequireddefaultchoicescomments
@{ k2 }@
{% if v2['version_added'] %} (added in @{v2['version_added']}@){% endif %}
{% if v2.get('required', False) %}yes{% else %}no{% endif %}{% if v2['default'] %}@{ v2['default'] }@{% endif %}
+ + + + + + + + + +{% for k2 in v['suboptions'] %} +{% set v2 = v['suboptions'] [k2] %} + + + + + +{% if v2.get('type', 'not_bool') == 'bool' %} - {% else %} - - {% endif %} - - {% endfor %} -
Dictionary object @{ k }@
parameterrequireddefaultchoicescomments
@{ k2 }@
{% if v2['version_added'] -%} (added in @{v2['version_added']}@){% endif -%}
{% if v2.get('required', False) -%}yes{% else -%}no{% endif -%}{% if v2['default'] -%}@{ v2['default'] }@{% endif -%}
  • yes
  • no
{% if v2['choices'] %}
    {% for choice in v2.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% endif %}		{% for desc in v2.description -%}
@{ desc | replace('\n', '\n ') | html_ify }@
{% endfor -%} {% if 'aliases' in v and v2.aliases -%}
-
aliases: @{ v2.aliases|join(', ') }@
{%- endif %} -
+{% else %} + 		{% if v2['choices'] -%}
    {% for choice in v2.get('choices',[]) -%}
  • @{ choice }@
    • {% endfor -%}
{% endif -%}		 +{% if v2.description is string %} +
@{ v2.description | replace('\n', '\n ') | html_ify }@
+{% else %} +{% for desc in v2.description %} +
@{ desc | replace('\n', '\n ') | html_ify }@
+{% endfor %} +{% endif %} +{% if 'aliases' in v and v2.aliases %} +
aliases: @{ v2.aliases|join(', ') }@
+{% endif %} +
+ - {% endif %} - - {% endfor %} +{% endif %} + + +{% endfor %} +
@@ -148,6 +186,7 @@ Common return values are documented here :doc:`common_return_values`, the follow .. raw:: html + @@ -155,19 +194,30 @@ Common return values are documented here :doc:`common_return_values`, the follow +{% for entry in returndocs %} - {% for entry in returndocs %} - - - - - + + + + + - {% if returndocs[entry].type == 'complex' %} - +{% if returndocs[entry].type == 'complex' %} + + + - - {% endif %} - {% endfor %} + + +{% endif %} +{% endfor %}
name descriptiontype sample
@{ entry }@ @{ returndocs[entry].description }@ @{ returndocs[entry].returned }@ @{ returndocs[entry].type }@ @{ returndocs[entry].sample}@ @{ entry }@ +{% if returndocs[entry].description is string %} +
@{ returndocs[entry].description | replace('\n', '\n ') | html_ify }@
+{% else %} +{% for desc in returndocs[entry].description %} +
@{ desc | replace('\n', '\n ') | html_ify }@
+{% endfor %} +{% endif %} + 		@{ returndocs[entry].returned }@@{ returndocs[entry].type }@@{ returndocs[entry].sample | replace('\n', '\n ') | html_ify }@
contains:
contains: + @@ -175,25 +225,34 @@ Common return values are documented here :doc:`common_return_values`, the follow +{% for sub in returndocs[entry].contains %} - {% for sub in returndocs[entry].contains %} - - - - - + + + + + - {% endfor %} +{% endfor %}
name descriptiontype sample
@{ sub }@ @{ returndocs[entry].contains[sub].description }@ @{ returndocs[entry].contains[sub].returned }@ @{ returndocs[entry].contains[sub].type }@ @{ returndocs[entry].contains[sub].sample}@ @{ sub }@ +{% if returndocs[entry].contains[sub].description is string %} +
@{ returndocs[entry].contains[sub].description | replace('\n', '\n ') | html_ify }@
+{% else %} +{% for desc in returndocs[entry].contains[sub].description %} +
@{ desc | replace('\n', '\n ') | html_ify }@
+{% endfor %} +{% endif %} + 		@{ returndocs[entry].contains[sub].returned }@@{ returndocs[entry].contains[sub].type }@@{ returndocs[entry].contains[sub].sample }@
-
-

+
+
{% endif %} {% if notes -%}