From 3716af8e07e3b2ad58c443b2d963ecf1bb1bf84e Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Tue, 14 Feb 2017 14:18:30 +0000
Subject: [PATCH] Use definition lists, not tables

Definition lists are a far better fit for config reference and produce
easier-to-parse output. Let's use them.

Change-Id: I7a4087c77e3aab8ddead4b30c5aa4e3b31b56704
---
 autogenerate_config_docs/autohelp.py          |  2 --
 .../templates/autohelp.rst.j2                 | 33 +++++++++----------
 2 files changed, 15 insertions(+), 20 deletions(-)

diff --git a/autogenerate_config_docs/autohelp.py b/autogenerate_config_docs/autohelp.py
index 6fa49a60..26e22fbd 100755
--- a/autogenerate_config_docs/autohelp.py
+++ b/autogenerate_config_docs/autohelp.py
@@ -536,8 +536,6 @@ def write_files(package_name, options, target, output_format):
         file_path = ("%(target)s/%(package_name)s-%(cat)s.%(ext)s" %
                      {'target': target, 'package_name': package_name,
                       'cat': cat, 'ext': ext})
-        # TODO(stephenfin): This template should be using definition lists
-        # rather than multiple tables
         tmpl_file = os.path.join(os.path.dirname(__file__),
                                  'templates/autohelp.%s.j2' % output_format)
         with open(tmpl_file) as fd:
diff --git a/autogenerate_config_docs/templates/autohelp.rst.j2 b/autogenerate_config_docs/templates/autohelp.rst.j2
index 23bed21f..58bbd71f 100644
--- a/autogenerate_config_docs/templates/autohelp.rst.j2
+++ b/autogenerate_config_docs/templates/autohelp.rst.j2
@@ -10,32 +10,29 @@
 
 .. _{{ table_label }}:
 
-.. list-table:: Description of {{ nice_cat }} configuration options
-   :header-rows: 1
-   :class: config-ref-table
+{{ nice_cat }}
+-----------------------------------------------------------------------
 
-   * - Configuration option = Default value
-     - Description
 {% for group in groups %}
-   * - **[{{ group }}]**
-     -
+
+{{ group }}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 {% for item in items[loop.index0] %}
-{% if item[1] is equalto '' %}
-   * - ``{{ item[0] }}`` =
-{% else %}
-   * - ``{{ item[0] }}`` = ``{{ item[2] }}``
+
+``{{ item[0] }}`` ({{ item[1] }})
+{% if item[2] is not equalto '' %}
+
+    Default: ``{{ item[2] }}``
 {% endif %}
 {% for paragraph in item[3] %}
-{% if loop.first %}
-     - ({{ item [1] }}) {{ paragraph }}
-{% else %}
-       {{ paragraph }}
-{% endif %}
 
+    {{ paragraph }}
 {% endfor %}
 {% for flagname, flagdesc in item[4] %}
-     - **{{ flagname }}**
-         {{ flagdesc }}
+
+    - **{{ flagname }}**
+
+      {{ flagdesc }}
 {% endfor %}
 {% endfor %}
 {% endfor %}