rnhmjoj/qutebrowser
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Many improvements for generate_doc

Browse Source
This commit is contained in:
Florian Bruhin 2014-09-07 20:11:38 +02:00
parent 02292d8518
commit 9f23e9aa36
1 changed files with 142 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
scripts/generate_doc.py
View File

@ -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."""
usage = cmd.parser.format_usage()
if usage.startswith('usage: '):
usage = usage[7:]
"""Get the command syntax for a command.
We monkey-patch the parser's formatter_class here to use our UsageFormatter
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_commands(fobj)
generate_settings('doc/settings.asciidoc')
generate_commands('doc/commands.asciidoc')
regenerate_authors('README.asciidoc')