From 53ecf9a455fb43a8ef4d1e795a739c9d01761d0b Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Tue, 21 Feb 2017 13:49:57 -0500
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                 | 34 +++++++++----------
 2 files changed, 16 insertions(+), 20 deletions(-)

diff --git a/autogenerate_config_docs/autohelp.py b/autogenerate_config_docs/autohelp.py
index dd6a01fb..d49dddb7 100755
--- a/autogenerate_config_docs/autohelp.py
+++ b/autogenerate_config_docs/autohelp.py
@@ -520,8 +520,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 8cd289c0..0b67ac72 100644
--- a/autogenerate_config_docs/templates/autohelp.rst.j2
+++ b/autogenerate_config_docs/templates/autohelp.rst.j2
@@ -10,36 +10,34 @@
 
 .. _{{ 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[2] is equalto '' %}
-   * - ``{{ item[0] }}`` =
+``{{ item[0] }}`` ({{ item[1] }})
+{% if item[2] is not equalto '' %}
+  Default: ``{{ item[2] }}``
 {% else %}
-   * - ``{{ item[0] }}`` = ``{{ item[2] }}``
+  Default: (none provided)
 {% endif %}
 {% for paragraph in item[3] %}
 
-{% if loop.first %}
-     - ({{ item [1] }}) {{ paragraph }}
-{% else %}
-       {{ paragraph }}
-{% endif %}
+  {{ paragraph }}
 {% endfor %}
+{% if item[4] %}
+
+  Flags:
 {% for flagname, flagdesc in item[4] %}
 
-       - **{{ flagname }}**
+  - **{{ flagname }}**
 
-         {{ flagdesc }}
-{% endfor %}
+    {{ flagdesc }}
+{% endfor %}
+{% endif %}
 {% endfor %}
 {% endfor %}