Nicer flag output in docs.

qutebrowser/commands/cmdutils.py

@@ -138,6 +138,8 @@ class register:  # pylint: disable=invalid-name
         self.parser = None
         self.func = None
         self.docparser = None
+        self.opt_args = collections.OrderedDict()
+        self.pos_args = []
         if modes is not None:
             for m in modes:
                 if not isinstance(m, usertypes.KeyMode):
@@ -180,7 +182,8 @@ class register:  # pylint: disable=invalid-name
             desc=desc, instance=self.instance, handler=func,
             completion=self.completion, modes=self.modes,
             not_modes=self.not_modes, needs_js=self.needs_js,
-            is_debug=self.debug, parser=self.parser, type_conv=type_conv)
+            is_debug=self.debug, parser=self.parser, type_conv=type_conv,
+            opt_args=self.opt_args, pos_args=self.pos_args)
         for name in names:
             cmd_dict[name] = cmd
         return func
@@ -259,10 +262,14 @@ class register:  # pylint: disable=invalid-name
         name = annotation_info.name or param.name
         shortname = annotation_info.flag or param.name[0]
         if self._get_type(param, annotation_info) == bool:
-            args.append('--{}'.format(name))
-            args.append('-{}'.format(shortname))
+            long_flag = '--{}'.format(name)
+            short_flag = '-{}'.format(shortname)
+            args.append(long_flag)
+            args.append(short_flag)
+            self.opt_args[name] = long_flag, short_flag
         else:
             args.append(name)
+            self.pos_args.append(name)
         return args
 
     def _param_to_argparse_kw(self, param, annotation_info):

qutebrowser/commands/command.py

@@ -52,7 +52,7 @@ class Command:
 
     def __init__(self, name, split, hide, count, desc, instance, handler,
                  completion, modes, not_modes, needs_js, is_debug, parser,
-                 type_conv):
+                 type_conv, opt_args, pos_args):
         # I really don't know how to solve this in a better way, I tried.
         # pylint: disable=too-many-arguments
         self.name = name
@@ -69,6 +69,8 @@ class Command:
         self.debug = is_debug
         self.parser = parser
         self.type_conv = type_conv
+        self.opt_args = opt_args
+        self.pos_args = pos_args
 
     def _check_prerequisites(self):
         """Check if the command is permitted to run currently.

scripts/generate_doc.py

@@ -153,14 +153,28 @@ def _get_command_doc(name, cmd):
     if parser.long_desc:
         output.append("")
         output.append(parser.long_desc)
-    if parser.arg_descs:
+
+    if cmd.pos_args:
         output.append("")
-        for arg, desc in parser.arg_descs.items():
-            text = desc.splitlines()
-            firstline = text[0].replace(', or None', '')
-            item = "* +{}+: {}".format(arg, firstline)
-            item += '\n'.join(text[1:])
-            output.append(item)
+        output.append('===== {}'.format("positional arguments"))
+        for arg in cmd.pos_args:
+            try:
+                output.append('* +{}+: {}'.format(arg, parser.arg_descs[arg]))
+            except KeyError as e:
+                raise KeyError("No description for arg {} of command "
+                               "'{}'!".format(e, cmd.name))
+
+    if cmd.opt_args:
+        output.append("")
+        output.append('===== {}'.format("optional arguments"))
+        for arg, (long_flag, short_flag) in cmd.opt_args.items():
+            try:
+                output.append('* +{}+, +{}+: {}'.format(
+                    short_flag, long_flag, parser.arg_descs[arg]))
+            except KeyError:
+                raise KeyError("No description for arg {} of command "
+                               "'{}'!".format(e, cmd.name))
+
     output.append("")
     output.append("")
     return '\n'.join(output)