Start implementing docstring parsing for generate_manpage

scripts/generate_manpage.py

@@ -25,14 +25,71 @@ sys.path.insert(0, os.getcwd())
 
 import qutebrowser.app
 import qutebrowser.commands.utils as cmdutils
+from qutebrowser.utils.usertypes import enum
+
+
+def get_command_doc(name, func):
+    """Generates documentation based on a docstring of a command handler.
+
+    The docstring needs to follow the format described in HACKING.
+    """
+    State = enum('short', 'desc', 'arg_start', 'arg_inside')
+
+    doc = inspect.getdoc(func)
+    lines = doc.splitlines()
+
+    cur_state = State.short
+
+    short_desc = []
+    long_desc = []
+    arg_descs = {}
+    cur_arg_name = None
+
+    for line in lines:
+        if cur_state == State.short:
+            if not line:
+                cur_state = State.desc
+            else:
+                short_desc.append(line.strip())
+        elif cur_state == State.desc:
+            if line.startswith('Args:'):
+                cur_state = State.arg_start
+            elif line.strip():
+                long_desc.append(line.strip())
+        elif cur_state == State.arg_start:
+            cur_arg_name, argdesc = line.split(':', maxsplit=1)
+            cur_arg_name = cur_arg_name.strip()
+            arg_descs[cur_arg_name] = [argdesc.strip()]
+            cur_state = State.arg_inside
+        elif cur_state == State.arg_inside:
+            if not line:
+                break
+            elif line[4:].startswith(' '):
+                arg_descs[cur_arg_name].append(line.strip())
+            else:
+                cur_arg_name, argdesc = line.split(':', maxsplit=1)
+                cur_arg_name = cur_arg_name.strip()
+                arg_descs[cur_arg_name] = [argdesc.strip()]
+
+    output = ['=== {}'.format(name)]
+    output.append(' '.join(short_desc))
+    output.append("")
+    output.append(' '.join(long_desc))
+    if arg_descs:
+        output.append('==== Arguments')
+        output.append("")
+        for arg, desc in arg_descs.items():
+            output.append("* {}: {}".format(arg, ' '.join(desc)))
+
+        output.append("")
+    output.append("")
+    return '\n'.join(output)
 
 
 def generate_commands():
     print("== Commands")
     for name, cmd in cmdutils.cmd_dict.items():
-        doc = inspect.getdoc(cmd.handler)
+        print(get_command_doc(name, cmd.handler))
-        print("=== " + name)
+
-        print(doc)
-        print()
 
 generate_commands()