From d9b3af523b0eb7be3bf71cd1d9ff9e22d3596f6c Mon Sep 17 00:00:00 2001
From: Toshio Kuratomi <a.badger@gmail.com>
Date: Tue, 13 Aug 2019 13:00:13 -0700
Subject: Galaxy meta docs table (#60171)

* Use an rst table instead of a raw html table

* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
  extraneous whitespace in the URL

* Normalize description data before sending them to the templates
---
 docs/docsite/_static/ansible.css              | 58 ++++++++++++++++++++--
 docs/templates/collections_galaxy_meta.rst.j2 | 70 +++++++++++++++------------
 docs/templates/plugin.rst.j2                  | 18 ++-----
 3 files changed, 97 insertions(+), 49 deletions(-)

(limited to 'docs')

diff --git a/docs/docsite/_static/ansible.css b/docs/docsite/_static/ansible.css
index 3fea13034a..336d35efd2 100644
--- a/docs/docsite/_static/ansible.css
+++ b/docs/docsite/_static/ansible.css
@@ -4,13 +4,63 @@
 /* override table width restrictions */
 @media screen and (min-width: 767px) {
 
+  /* If we ever publish to read the docs, we need to use !important for these
+   * two styles as read the docs itself loads their theme in a way that we
+   * can't otherwise override it.
+   */
    .wy-table-responsive table td {
-      /* !important prevents the common CSS stylesheets from overriding
-         this as on RTD they are loaded after this stylesheet */
-      white-space: normal !important;
+      white-space: normal;
    }
 
    .wy-table-responsive {
-      overflow: visible !important;
+      overflow: visible;
    }
 }
+
+/*
+ * We use the class documentation-table for attribute tables where the first
+ * column is the name of an attribute and the second column is the description.
+ */
+
+/* These tables look like this:
+ * 
+ *  Attribute Name     Description
+ *  --------------     -----------
+ *  **NAME**           This is a multi-line description
+ *  str/required       that can span multiple lines
+ *
+ *                     With multiple paragraphs
+ *  --------------     -----------
+ *
+ * **NAME** is given the class .value-name
+ * str is given the class .value-type
+ * / is given the class .value-separator
+ * required is given the class .value-required
+ */
+
+table.documentation-table td:first-child {
+    white-space: nowrap;
+    vertical-align: top;
+}
+
+table.documentation-table .value-name {
+    font-weight: bold;
+    display: inline;
+}
+
+table.documentation-table .value-type {
+    font-size: x-small;
+    color: purple;
+    display: inline;
+}
+
+table.documentation-table .value-separator {
+    font-size: x-small;
+    display: inline;
+}
+
+table.documentation-table .value-required {
+    font-size: x-small;
+    color: red;
+    display: inline;
+}
diff --git a/docs/templates/collections_galaxy_meta.rst.j2 b/docs/templates/collections_galaxy_meta.rst.j2
index 87c530e076..cb3568b32a 100644
--- a/docs/templates/collections_galaxy_meta.rst.j2
+++ b/docs/templates/collections_galaxy_meta.rst.j2
@@ -16,38 +16,44 @@ Structure
 
 The ``galaxy.yml`` file must contain the following keys in valid YAML:
 
-.. raw:: html
-
-    <table  border=0 cellpadding=0 class="documentation-table">
-        {# Header of the documentation -#}
-        <tr>
-            <th>Key</th>
-            <th width="100%">Comments</th>
-        </tr>
-        {% for entry in options %}
-            <tr>
-                {# key name with required or type label #}
-                <td>
-                    <b>@{ entry.key }@</b>
-                    <div style="font-size: small">
-                        <span style="color: purple">@{ entry.type | documented_type }@</span>
-                        {% if entry.get('required', False) %} / <span style="color: red">required</span>{% endif %}
-                    </div>
-                </td>
-                {# Comments #}
-                <td>
-                    {% if entry.description is string %}
-                        <div>@{ entry.description | replace('\n', '\n    ') | html_ify }@</div>
-                    {% else %}
-                        {% for desc in entry.description %}
-                            <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
-                        {% endfor %}
-                    {% endif %}
-                </td>
-            </tr>
-        {% endfor %}
-    </table>
-    <br/>
+
+.. rst-class:: documentation-table
+
+.. list-table::
+    :header-rows: 1
+    :widths: auto
+
+    * - Key
+      - Comment
+
+{%- for entry in options %}
+
+
+    * - .. rst-class:: value-name
+
+        @{ entry.key }@ |br|
+
+        .. rst-class:: value-type
+
+        @{ entry.type | documented_type }@ |_|
+
+        {% if entry.get('required', False) -%}
+        .. rst-class:: value-separator
+
+        / |_|
+
+        .. rst-class:: value-required
+
+        required
+        {%- endif %}
+
+
+      - {% for desc in entry.description -%}
+        @{ desc | trim | rst_ify }@
+
+        {% endfor -%}
+{%- endfor %}
+
 
 Examples
 ========
diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 65acbb2e22..2edbad34d0 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -50,13 +50,9 @@ Synopsis
 --------
 {% if description -%}
 
-{%   if description is string -%}
-- @{ description | rst_ify }@
-{%   else %}
-{%     for desc in description %}
+{%   for desc in description %}
 - @{ desc | rst_ify }@
-{%     endfor %}
-{%   endif %}
+{%   endfor %}
 
 {% endif %}
 
@@ -183,13 +179,9 @@ Parameters
                 {% 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 %}
+                    {% for desc in value.description %}
+                        <div>@{ desc | replace('\n', '\n    ') | html_ify }@</div>
+                    {% endfor %}
                     {% if 'aliases' in value and value.aliases %}
                         <div style="font-size: small; color: darkgreen"><br/>aliases: @{ value.aliases|join(', ') }@</div>
                     {% endif %}
-- 
cgit v1.2.1