From 6290b73863b8098a4bf6f5d28e7a2cb1361277df Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Tue, 20 Jun 2017 11:19:26 +0200
Subject: [PATCH] docs: more compact options formatting

---
 docs/borg_theme/css/borg.css | 26 +++++++++++++++++++++---
 docs/conf.py                 |  8 ++++++++
 setup.py                     | 38 ++++++++++++++++--------------------
 3 files changed, 48 insertions(+), 24 deletions(-)

diff --git a/docs/borg_theme/css/borg.css b/docs/borg_theme/css/borg.css
index 3394f49c2..abd7b7a1a 100644
--- a/docs/borg_theme/css/borg.css
+++ b/docs/borg_theme/css/borg.css
@@ -109,7 +109,8 @@ table.docutils:not(.footnote) th {
     border: 1px solid #ddd;
 }
 
-table.docutils:not(.footnote) tr:first-child th {
+table.docutils:not(.footnote) tr:first-child th,
+table.docutils:not(.footnote) tr:first-child td {
     border-top: 0;
 }
 
@@ -118,15 +119,18 @@ table.docutils:not(.footnote) tr:last-child td {
 }
 
 table.docutils:not(.footnote) tr td:first-child,
-table.docutils:not(.footnote) tr th:first-child {
+table.docutils:not(.footnote) tr th:first-child,
+table.docutils.option-list tr td {
     border-left: 0;
 }
 
 table.docutils:not(.footnote) tr td:last-child,
-table.docutils:not(.footnote) tr th:last-child {
+table.docutils:not(.footnote) tr th:last-child,
+table.docutils.option-list tr td {
     border-right: 0;
 }
 
+kbd, /* used in usage pages for options */
 code,
 .rst-content tt.literal,
 .rst-content tt.literal,
@@ -141,6 +145,22 @@ p .literal span {
     background: none;
 }
 
+kbd {
+    box-shadow: none;
+    line-height: 23px;
+    word-wrap: normal;
+    font-size: 15px;
+    font-family: Consolas, monospace;
+}
+
+kbd .option {
+    white-space: nowrap;
+}
+
+table.docutils.option-list td.option-group {
+    min-width: 10em;
+}
+
 cite {
     white-space: nowrap;
     color: black; /* slight contrast with #404040 of regular text */
diff --git a/docs/conf.py b/docs/conf.py
index 8f6b867c7..283a2c7ac 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -105,8 +105,16 @@ html_theme_path = guzzle_sphinx_theme.html_theme_path()
 html_theme = 'guzzle_sphinx_theme'
 
 
+def set_rst_settings(app):
+    app.env.settings.update({
+        'field_name_limit': 0,
+        'option_limit': 0,
+    })
+
+
 def setup(app):
     app.add_stylesheet('css/borg.css')
+    app.connect('builder-inited', set_rst_settings)
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/setup.py b/setup.py
index 3b9b495ba..2b58dcdf5 100644
--- a/setup.py
+++ b/setup.py
@@ -285,6 +285,7 @@ class build_usage(Command):
             if option.option_strings:
                 continue
             fp.write(' ' + option.metavar)
+        fp.write('\n\n')
 
     def write_options(self, parser, fp):
         for group in parser._action_groups:
@@ -298,12 +299,13 @@ class build_usage(Command):
         def is_positional_group(group):
             return any(not o.option_strings for o in group._group_actions)
 
-        def get_help(option):
-            text = textwrap.dedent((option.help or '') % option.__dict__)
-            return '\n'.join('| ' + line for line in text.splitlines())
+        indent = ' ' * base_indent
 
-        def shipout(text):
-            fp.write(textwrap.indent('\n'.join(text), ' ' * base_indent))
+        if is_positional_group(group):
+            for option in group._group_actions:
+                fp.write(option.metavar + '\n')
+                fp.write(textwrap.indent(option.help or '', ' ' * base_indent) + '\n')
+            return
 
         if not group._group_actions:
             return
@@ -311,28 +313,22 @@ class build_usage(Command):
         if with_title:
             fp.write('\n\n')
             fp.write(group.title + '\n')
-        text = []
 
-        if is_positional_group(group):
-            for option in group._group_actions:
-                text.append(option.metavar)
-                text.append(textwrap.indent(option.help or '', ' ' * 4))
-            shipout(text)
-            return
+        opts = OrderedDict()
 
-        options = []
         for option in group._group_actions:
             if option.metavar:
-                option_fmt = '``%%s %s``' % option.metavar
+                option_fmt = '%s ' + option.metavar
             else:
-                option_fmt = '``%s``'
+                option_fmt = '%s'
             option_str = ', '.join(option_fmt % s for s in option.option_strings)
-            options.append((option_str, option))
-        for option_str, option in options:
-            help = textwrap.indent(get_help(option), ' ' * 4)
-            text.append(option_str)
-            text.append(help)
-        shipout(text)
+            option_desc = textwrap.dedent((option.help or '') % option.__dict__)
+            opts[option_str] = textwrap.indent(option_desc, ' ' * 4)
+
+        padding = len(max(opts)) + 1
+
+        for option, desc in opts.items():
+            fp.write(indent + option.ljust(padding) + desc + '\n')
 
 
 class build_man(Command):