docs: Document list-tables as recommended

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/docs/styleguide.rst b/docs/styleguide.rst
index 3162868fb7535a459c7d71495d9c0e0ee6211e24..34c5b1573a99fd14cb9d2d71401eb7289f67c38a 100644 (file)
--- a/docs/styleguide.rst
+++ b/docs/styleguide.rst
@@ -77,6 +77,26 @@ which allows for 6 levels of headings
    Heading 6
    ^^^^^^^^^
 
+Tables
+======
+
+Tables should be created using the ``list-table`` directive whenever
+possible, as in
+
+::
+
+   .. list-table::
+      :header-rows: 1
+
+      * - Option
+        - Description
+
+      * - ``foo_enabled``
+        - Whether or not ``foo`` should be enabled
+
+      * - ``bar_user``
+        - Which user to run ``bar`` as
+
 Manual pages
 ============