docs: more compact options formatting

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 */

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

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):
+        indent = ' ' * base_indent
-            text = textwrap.dedent((option.help or '') % option.__dict__)
-            return '\n'.join('| ' + line for line in text.splitlines())
 
-        def shipout(text):
+        if is_positional_group(group):
-            fp.write(textwrap.indent('\n'.join(text), ' ' * base_indent))
+            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):
+        opts = OrderedDict()
-            for option in group._group_actions:
-                text.append(option.metavar)
-                text.append(textwrap.indent(option.help or '', ' ' * 4))
-            shipout(text)
-            return
 
-        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))
+            option_desc = textwrap.dedent((option.help or '') % option.__dict__)
-        for option_str, option in options:
+            opts[option_str] = textwrap.indent(option_desc, ' ' * 4)
-            help = textwrap.indent(get_help(option), ' ' * 4)
+
-            text.append(option_str)
+        padding = len(max(opts)) + 1
-            text.append(help)
+
-        shipout(text)
+        for option, desc in opts.items():
+            fp.write(indent + option.ljust(padding) + desc + '\n')
 
 
 class build_man(Command):