From 496ce388ab4dc464b9b3f821e05b98ebfc7fb17f Mon Sep 17 00:00:00 2001
From: Wolfgang Felbermeier <wf@felbermeier.com>
Date: Wed, 22 Nov 2017 22:53:53 +0100
Subject: [PATCH] documentation: render nested return dicts for more then one
 level (#33143)

* Render nested return value documentation for more then one level
in the generated webdocs.

* Remove unnecessary code and cleanup

* Implement recursive option documentation

* Build elbow intendation style for options and return documentation
---
 .../docsite/_themes/srtd/static/css/theme.css |  47 ++-
 docs/templates/plugin.rst.j2                  | 336 ++++++++----------
 2 files changed, 196 insertions(+), 187 deletions(-)

diff --git a/docs/docsite/_themes/srtd/static/css/theme.css b/docs/docsite/_themes/srtd/static/css/theme.css
index f1a2f685ef7..9a0a84a6384 100644
--- a/docs/docsite/_themes/srtd/static/css/theme.css
+++ b/docs/docsite/_themes/srtd/static/css/theme.css
@@ -4748,7 +4748,7 @@ th, td {
 }
 
 table {
-       overflow-x: scroll;
+       overflow-x: auto;
        display: block;
        max-width: 100%;
 }
@@ -4864,3 +4864,48 @@ table {
         padding: 8px 13px;
     }
 }
+
+.outer-elbow-container {
+    display: flex;
+    height: 100%;
+    flex-direction: row;
+}
+
+.elbow-placeholder {
+    border-left: 1px solid #000;
+    height: 100%;
+    width: 30px;
+}
+
+.elbow-key {
+    height: 100%;
+    padding: 4px;
+    border-top: 1px solid #000;
+    flex-grow: 1;
+    border-left: 1px solid #000;
+}
+
+.elbow-blocker {
+    height: 0;
+    overflow: hidden;
+}
+
+.return-value-column {
+    height: 1px
+}
+
+.return-value-column td {
+    height: inherit
+}
+
+.cell-border {
+    padding: 4px;
+    border-left: 1px solid #000;
+    border-top: 1px solid #000;
+    height: 100%;
+}
+
+.documentation-table {
+    border-right: 1px solid #000;
+    border-bottom: 1px solid #000;
+}
\ No newline at end of file
diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 0fb1ac6712f..6d93079a4e1 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -86,135 +86,103 @@ Options
 
 .. raw:: html
 
-    <table border=1 cellpadding=4>
-
-    <tr>
-    <th class="head">parameter</th>
-    <th class="head">required</th>
-    <th class="head">default</th>
-    <th class="head">choices</th>
-{% if plugin_type != 'module' %}
-    <th class="head">configuration</th>
-{% endif %}
-    <th class="head">comments</th>
-    </tr>
-{% for k in option_keys -%}
-{% set v = options[k] -%}
-{% if not v['suboptions'] %}
-
-    <tr>
-    <td>@{ k }@<br/><div style="font-size: small;">{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}</div></td>
-    <td>{% if v.get('required', False) -%}yes{% else %}no{% endif -%}</td>
-    <td>{% if v['default'] -%}@{ v['default'] }@{% endif -%}</td>
-{% if v.get('type', 'not_bool') == 'bool' %}
-    <td><ul><li>yes</li><li>no</li></ul></td>
-{% else %}
-    <td>{% if v['choices'] -%}<ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul>{% endif -%}</td>
-{% endif %}
-{% if plugin_type != 'module' %}
-    <td>
-	{% if 'ini' in v %}
-	<div> ini entries:
-	{% for ini in v.get('ini') %}
-        <p>[@{ ini.section }@ ]<br>@{ ini.key}@ = @{ v['default']|default('VALUE') }@</p>
-	{% endfor %}
-	</div>
-	{% endif %}
-	{% if 'env' in v %}
-	{% for env in v.get('env') %}
-        <div>env:@{ env.name }@</div>
-	{% endfor %}
-	{% endif %}
-	{% if 'vars' in v %}
-	{% for myvar in v.get('vars') %}
-        <div>var: @{ myvar.name }@</div>
-	{% endfor %}
-	{% endif %}
-	</td>
-{% endif %}
-	<td>
-{% if v.description is string %}
-        <div>@{ v.description | replace('\n', '\n    ') | html_ify }@</div>
-{% else %}
-{% for desc in v.description %}
-        <p>@{ desc | replace('\n', '\n    ') | html_ify }@</p>
-{% endfor %}
-{% endif %}
-{% if 'aliases' in v and v.aliases %}
-        </br><div style="font-size: small;">aliases: @{ v.aliases|join(', ') }@</div>
-{% endif %}
-	</td>
-	</tr>
-{% else %}
-    <tr>
-    <td rowspan="2">@{ k }@<br/><div style="font-size: small;">{% if v['version_added'] -%} (added in @{v['version_added']}@){% endif -%}</div></td>
-    <td>{% if v.get('required', False) -%}yes{% else -%}no{% endif -%}</td>
-    <td></td>
-{% if plugin_type != 'module' %}
-    <td></td>
-{% endif %}
-    <td></td>
-    <td>
-{% if v.description is string %}
-        <div>@{ v.description | replace('\n', '\n    ') | html_ify }@</div>
-{% else %}
-{% for desc in v.description %}
-        <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-{% endfor %}
-{% endif %}
-{% if 'aliases' in v and v.aliases %}
-        </br><div style="font-size: small;">aliases: @{ v.aliases|join(', ') }@</div>
-{% endif %}
-    </tr>
-
-    <tr>
-    <td colspan="5">
-        <table border=1 cellpadding=4>
-        <caption><b>Dictionary object @{ k }@</b></caption>
-
+    <table  border=0 cellpadding=0 class="documentation-table">
+        {# Header of the documentation #}
         <tr>
-        <th class="head">parameter</th>
-        <th class="head">required</th>
-        <th class="head">default</th>
-        <th class="head">choices</th>
-        <th class="head">comments</th>
+            <th class="head"><div class="cell-border">parameter</div></th>
+            <th class="head"><div class="cell-border">required</div></th>
+            <th class="head"><div class="cell-border">default</div></th>
+            <th class="head"><div class="cell-border">choices</div></th>
+            {% if plugin_type != 'module' %}
+                <th class="head"><div class="cell-border">configuration</div></th>
+            {% endif %}
+            <th class="head"><div class="cell-border">comments</div></th>
         </tr>
-{% for k2 in v['suboptions'] %}
-{% set v2 = v['suboptions'] [k2] %}
-
-        <tr>
-        <td>@{ k2 }@<br/><div style="font-size: small;">{% if v2['version_added'] -%} (added in @{v2['version_added']}@){% endif -%}</div></td>
-        <td>{% if v2.get('required', False) -%}yes{% else -%}no{% endif -%}</td>
-        <td>{% if v2['default'] -%}@{ v2['default'] }@{% endif -%}</td>
-{% if v2.get('type', 'not_bool') == 'bool' %}
-        <td><ul><li>yes</li><li>no</li></ul></td>
-{% else %}
-        <td>{% if v2['choices'] -%}<ul>{% for choice in v2.get('choices',[]) -%}<li>@{ choice }@</li>{% endfor -%}</ul>{% endif -%}</td>
-{% endif %}
-        <td>
-{% if v2.description is string %}
-        <div>@{ v2.description | replace('\n', '\n    ') | html_ify }@</div>
-{% else %}
-{% for desc in v2.description %}
-            <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-{% endfor %}
-{% endif %}
-{% if 'aliases' in v and v2.aliases %}
-            </br><div style="font-size: small;">aliases: @{ v2.aliases|join(', ') }@</div>
-{% endif %}
-        </td>
-        </tr>
-{% endfor %}
-
-        </table>
-
-    </td>
-    </tr>
-{% endif %}
-    </td>
-    </tr>
-{% endfor %}
-
+        {% for key, value in options.items() recursive %}
+            <tr class="return-value-column">
+                {# parameter name with introduced label #}
+                <td>
+                    <div class="outer-elbow-container">
+                        {% for i in range(1, loop.depth) %}
+                            <div class="elbow-placeholder">
+                            </div>
+                        {% endfor %}
+                        <div class="elbow-key">
+                            @{ key }@<br/><div style="font-size: small;">{% if value.version_added %} (added in @{value.version_added}@){% endif %}</div>
+                        </div>
+                    <div class="outer-elbow-container">
+                </td>
+                {# required #}
+                <td><div class="cell-border">{% if value.get('required', False) %}yes{% else %}no{% endif %}</div></td>
+                {# default value #}
+                <td><div class="cell-border">{% if value.default %}@{ value.default }@{% endif %}</div></td>
+                {# choices #}
+                <td>
+                    <div class="cell-border">
+                        {% if value.type == 'boolean' %}
+                            <ul>
+                                <li>yes</li>
+                                <li>no</li>
+                            </ul>
+                        {% else %}
+                            {% if value.choices %}
+                                <ul>
+                                    {% for choice in value.choices %}
+                                        <li>@{ choice }@</li>
+                                    {% endfor %}
+                                </ul>
+                            {% endif %}
+                        {% endif %}
+                    </div>
+                </td>
+                {# configuration #}
+                {% if plugin_type != 'module' %}
+                    <td>
+                        <div class="cell-border">
+                            {% 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 %}
+                        </div>
+                    </td>
+                {% endif %}
+                {# description #}
+                <td>
+                    <div class="cell-border">
+                        {% if value.description is string %}
+                            <div>@{ value.description | replace('\n', '\n    ') | html_ify }@</div>
+                        {% else %}
+                            {% for desc in value.description %}
+                                <p>@{ desc | replace('\n', '\n    ') | html_ify }@</p>
+                            {% endfor %}
+                        {% endif %}
+                        {% if 'aliases' in value and value.aliases %}
+                            </br><div style="font-size: small;">aliases: @{ value.aliases|join(', ') }@</div>
+                        {% endif %}
+                    </div>
+                </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>
 
@@ -245,68 +213,64 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
 
 .. raw:: html
 
-    <table border=1 cellpadding=4>
-
-    <tr>
-    <th class="head">name</th>
-    <th class="head">description</th>
-    <th class="head">returned</th>
-    <th class="head">type</th>
-    <th class="head">sample</th>
-    </tr>
-{% for entry in returndocs %}
-
-    <tr>
-    <td>@{ entry }@</td>
-    <td>
-{% if returndocs[entry].description is string %}
-        <div>@{ returndocs[entry].description | replace('\n', '\n    ') | html_ify }@</div>
-{% else %}
-{% for desc in returndocs[entry].description %}
-        <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-{% endfor %}
-{% endif %}
-    </td>
-    <td align=center>@{ returndocs[entry].returned }@</td>
-    <td align=center>@{ returndocs[entry].type }@</td>
-    <td align=center>@{ returndocs[entry].sample | replace('\n', '\n    ') | html_ify }@</td>
-    </tr>
-{% if returndocs[entry].type == 'complex' %}
-
-    <tr>
-    <td>contains:</td>
-    <td colspan=4>
-        <table border=1 cellpadding=2>
+    <style>
+        .outer-elbow-container{display: flex;height:100%;flex-direction:row;}
+        .elbow-placeholder{border-left:1px solid #000;height:100%;width:30px;}
+        .elbow-key{height:100%;padding:4px;border-top:1px solid #000;flex-grow:1;border-left:1px solid #000;}
+        .elbow-blocker{height:0;overflow:hidden;}
+        .return-value-column{height:1px}
+        .return-value-column td{height:inherit}
+        .cell-border{padding:4px;border-left:1px solid #000; border-top:1px solid #000;height:100%;}
+        .documentation-table{border-right:1px solid #000;border-bottom:1px solid #000;}
+    </style>
 
+    <table border=0 cellpadding=0 class="documentation-table">
         <tr>
-        <th class="head">name</th>
-        <th class="head">description</th>
-        <th class="head">returned</th>
-        <th class="head">type</th>
-        <th class="head">sample</th>
+            <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">returned</div></th>
+            <th class="head"><div class="cell-border">type</div></th>
+            <th class="head"><div class="cell-border">sample</div></th>
         </tr>
-{% for sub in returndocs[entry].contains %}
-
-        <tr>
-        <td>@{ sub }@</td>
-        <td>
-{% if returndocs[entry].contains[sub].description is string %}
-            <div>@{ returndocs[entry].contains[sub].description | replace('\n', '\n    ') | html_ify }@</div>
-{% else %}
-{% for desc in returndocs[entry].contains[sub].description %}
-            <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-{% endfor %}
-{% endif %}
-        </td>
-        <td align=center>@{ returndocs[entry].contains[sub].returned }@</td>
-        <td align=center>@{ returndocs[entry].contains[sub].type }@</td>
-        <td align=center>@{ returndocs[entry].contains[sub].sample }@</td>
-        </tr>
-{% endfor %}
-        </table>
-	</td></tr>
-{% endif %}
-{% endfor %}
+        {% for key, value in returndocs.items() 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">
+                            @{ key }@
+                        </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 align=center><div class="cell-border">@{ value.returned }@</div></td>
+                <td align=center><div class="cell-border">@{ value.type }@</div></td>
+                <td align=center><div class="cell-border">@{ value.sample | replace('\n', '\n    ') | html_ify }@</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 %}