Many improvements for generate_doc

scripts/generate_doc.py

@@ -28,6 +28,7 @@ import inspect
 import subprocess
 import collections
 import tempfile
+import argparse
 
 sys.path.insert(0, os.getcwd())
 
@@ -40,16 +41,71 @@ from qutebrowser.config import configdata
 from qutebrowser.utils import utils
 
 
+class UsageFormatter(argparse.HelpFormatter):
+
+    """Patched HelpFormatter to include some asciidoc markup in the usage.
+
+    This does some horrible things, but the alternative would be to reimplement
+    argparse.HelpFormatter while copying 99% of the code :-/
+    """
+
+    def _format_usage(self, usage, actions, groups, _prefix):
+        """Override _format_usage to not add the 'usage:' prefix."""
+        return super()._format_usage(usage, actions, groups, '')
+
+    def _metavar_formatter(self, action, default_metavar):
+        """Override _metavar_formatter to add asciidoc markup to metavars.
+
+        Most code here is copied from Python 3.4's argparse.py.
+        """
+        if action.metavar is not None:
+            result = "'{}'".format(action.metavar)
+        elif action.choices is not None:
+            choice_strs = [str(choice) for choice in action.choices]
+            result = '{%s}' % ','.join('*{}*'.format(e) for e in choice_strs)
+        else:
+            result = "'{}'".format(default_metavar)
+
+        def fmt(tuple_size):
+            if isinstance(result, tuple):
+                return result
+            else:
+                return (result, ) * tuple_size
+        return fmt
+
+    def _format_actions_usage(self, actions, groups):
+        """Override _format_actions_usage to add asciidoc markup to flags.
+
+        Because argparse.py's _format_actions_usage is very complex, we first
+        monkey-patch the option strings to include the asciidoc markup, then
+        run the original method, then undo the patching.
+        """
+        old_option_strings = {}
+        for action in actions:
+            old_option_strings[action] = action.option_strings[:]
+            action.option_strings = ['*{}*'.format(s)
+                                     for s in action.option_strings]
+        ret = super()._format_actions_usage(actions, groups)
+        for action in actions:
+            action.option_strings = old_option_strings[action]
+        return ret
+
+
 def _open_file(name, mode='w'):
     """Open a file with a preset newline/encoding mode."""
     return open(name, mode, newline='\n', encoding='utf-8')
 
 
 def _get_cmd_syntax(name, cmd):
-    """Get the command syntax for a command."""
+    """Get the command syntax for a command.
-    usage = cmd.parser.format_usage()
+
-    if usage.startswith('usage: '):
+    We monkey-patch the parser's formatter_class here to use our UsageFormatter
-        usage = usage[7:]
+    which adds some asciidoc markup.
+    """
+    old_fmt_class = cmd.parser.formatter_class
+    cmd.parser.formatter_class = UsageFormatter
+    usage = cmd.parser.format_usage().rstrip()
+    cmd.parser.formatter_class = old_fmt_class
     return usage
 
 
@@ -61,7 +117,7 @@ def _get_command_quickref(cmds):
     out.append('|Command|Description')
     for name, cmd in cmds:
         desc = inspect.getdoc(cmd.handler).splitlines()[0]
-        out.append('|<<cmd-{},{}>>|{}'.format(name, name, desc))
+        out.append('|<<{},{}>>|{}'.format(name, name, desc))
     out.append('|==============')
     return '\n'.join(out)
 
@@ -86,7 +142,7 @@ def _get_setting_quickref():
 
 def _get_command_doc(name, cmd):
     """Generate the documentation for a command."""
-    output = ['[[cmd-{}]]'.format(name)]
+    output = ['[[{}]]'.format(name)]
     output += ['==== {}'.format(name)]
     syntax = _get_cmd_syntax(name, cmd)
     if syntax != name:
@@ -94,6 +150,7 @@ def _get_command_doc(name, cmd):
         output.append("")
     parser = utils.DocstringParser(cmd.handler)
     output.append(parser.short_desc)
+    if parser.long_desc:
         output.append("")
         output.append(parser.long_desc)
     if parser.arg_descs:
@@ -154,8 +211,9 @@ def _format_action(action):
     return '{}\n    {}\n'.format(invocation, action.help)
 
 
-def generate_commands(f):
+def generate_commands(filename):
     """Generate the complete commands section."""
+    with _open_file(filename) as f:
         f.write('\n')
         f.write("== COMMANDS\n")
         normal_cmds = []
@@ -174,28 +232,30 @@ def generate_commands(f):
         f.write("\n")
         f.write("=== Normal commands\n")
         f.write(".Quick reference\n")
-    f.write(_get_command_quickref(normal_cmds) + "\n")
+        f.write(_get_command_quickref(normal_cmds) + "\n\n")
         for name, cmd in normal_cmds:
-        f.write(_get_command_doc(name, cmd) + "\n")
+            f.write(_get_command_doc(name, cmd))
         f.write("\n")
         f.write("=== Hidden commands\n")
         f.write(".Quick reference\n")
-    f.write(_get_command_quickref(hidden_cmds) + "\n")
+        f.write(_get_command_quickref(hidden_cmds))
         for name, cmd in hidden_cmds:
-        f.write(_get_command_doc(name, cmd) + "\n")
+            f.write(_get_command_doc(name, cmd))
         f.write("\n")
         f.write("=== Debugging commands\n")
         f.write("These commands are mainly intended for debugging. They are "
-            "hidden if qutebrowser was started without the `--debug`-flag.\n")
+                "hidden if qutebrowser was started without the "
+                "`--debug`-flag.\n")
         f.write("\n")
         f.write(".Quick reference\n")
-    f.write(_get_command_quickref(debug_cmds) + "\n")
+        f.write(_get_command_quickref(debug_cmds))
         for name, cmd in debug_cmds:
-        f.write(_get_command_doc(name, cmd) + "\n")
+            f.write(_get_command_doc(name, cmd))
 
 
-def generate_settings(f):
+def generate_settings(filename):
     """Generate the complete settings section."""
+    with _open_file(filename) as f:
         f.write("\n")
         f.write("== SETTINGS\n")
         f.write(_get_setting_quickref() + "\n")
@@ -208,7 +268,7 @@ def generate_settings(f):
             else:
                 for optname, option in sect.items():
                     f.write("\n")
-                f.write('[[setting-{}-{}]]'.format(sectname, optname) + "\n")
+                    f.write('[[{}-{}]]'.format(sectname, optname) + "\n")
                     f.write("==== {}".format(optname) + "\n")
                     f.write(sect.descriptions[optname] + "\n")
                     f.write("\n")
@@ -312,6 +372,6 @@ def regenerate_manpage(filename):
 
 if __name__ == '__main__':
     regenerate_manpage('doc/qutebrowser.1.asciidoc')
-    #generate_settings(fobj)
+    generate_settings('doc/settings.asciidoc')
-    #generate_commands(fobj)
+    generate_commands('doc/commands.asciidoc')
     regenerate_authors('README.asciidoc')