Prettier formatting of detailed opt information

Most of what's requested in the linked bug is already handled, albeit
not in as pretty manner as possible. The remainder - type and boolean -
are hard to represent cleanly and should be described in the option help
text.

Signed-off-by: Stephen Finucane <stephen@that.guru>
Closes: #6

Author: stephenfin

sphinx_click/ext.py

@@ -51,34 +51,44 @@ def _write_opts(opts):
     if opt.secondary_opts:
         rv.append(_write_opts(opt.secondary_opts))
 
-    help = opt.help or ''
-    extra = []
+    out = []
+    if opt.help:
+        if opt.required:
+            out.append('**Required** %s' % opt.help)
+        else:
+            out.append(opt.help)
+    else:
+        if opt.required:
+            out.append('**Required**')
+
+    extras = []
+
     if opt.default is not None and opt.show_default:
         if isinstance(opt.show_default, str):
             # Starting from Click 7.0 this can be a string as well. This is
             # mostly useful when the default is not a constant and
             # documentation thus needs a manually written string.
-            extra.append('default: %s' % opt.show_default)
+            extras.append(':default: %s' % opt.show_default)
         else:
-            extra.append(
-                'default: %s'
+            extras.append(
+                ':default: %s'
                 % (
                     ', '.join('%s' % d for d in opt.default)
                     if isinstance(opt.default, (list, tuple))
                     else opt.default,
                 )
             )
-    if opt.required:
-        extra.append('required')
-    if extra:
-        help = '%s[%s]' % (help and help + '  ' or '', '; '.join(extra))
+
     if isinstance(opt.type, click.Choice):
-        help = "%s\n\n:options: %s" % (
-            help and help + "  " or "",
-            "|".join(opt.type.choices),
-        )
+        extras.append(':options: %s' % '|'.join(opt.type.choices))
+
+    if extras:
+        if out:
+            out.append('')
+
+        out.extend(extras)
 
-    return ', '.join(rv), help
+    return ', '.join(rv), '\n'.join(out)
 
 
 def _format_description(ctx):

tests/test_formatter.py

@@ -142,11 +142,11 @@ def foobar(bar):
 
         .. option:: --num-param <num_param>
 
-            [default: 42]
+            :default: 42
 
         .. option:: --param <param>
 
-            [default: Something computed at runtime]
+            :default: Something computed at runtime
         """
             ).lstrip(),
             '\n'.join(output),
@@ -208,7 +208,7 @@ def hello(name):
 
         .. option:: --name <name>
 
-            Name to say hello to.  [required]
+            **Required** Name to say hello to.
         """
             ).lstrip(),
             '\n'.join(output),