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

224
scripts/generate_doc.py
View File

@ -28,6 +28,7 @@ import inspect
import subprocess import subprocess
import collections import collections
import tempfile import tempfile
import argparse
sys.path.insert(0, os.getcwd()) sys.path.insert(0, os.getcwd())
@ -40,16 +41,71 @@ from qutebrowser.config import configdata
from qutebrowser.utils import utils 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'): def _open_file(name, mode='w'):
"""Open a file with a preset newline/encoding mode.""" """Open a file with a preset newline/encoding mode."""
return open(name, mode, newline='\n', encoding='utf-8') return open(name, mode, newline='\n', encoding='utf-8')
def _get_cmd_syntax(name, cmd): 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 return usage
@ -61,7 +117,7 @@ def _get_command_quickref(cmds):
out.append('|Command|Description') out.append('|Command|Description')
for name, cmd in cmds: for name, cmd in cmds:
desc = inspect.getdoc(cmd.handler).splitlines()[0] desc = inspect.getdoc(cmd.handler).splitlines()[0]
out.append('|<<cmd-{},{}>>|{}'.format(name, name, desc)) out.append('|<<{},{}>>|{}'.format(name, name, desc))
out.append('|==============') out.append('|==============')
return '\n'.join(out) return '\n'.join(out)
@ -86,16 +142,17 @@ def _get_setting_quickref():
def _get_command_doc(name, cmd): def _get_command_doc(name, cmd):
"""Generate the documentation for a command.""" """Generate the documentation for a command."""
output = ['[[cmd-{}]]'.format(name)] output = ['[[{}]]'.format(name)]
output += ['==== {}'.format(name)] output += ['==== {}'.format(name)]
syntax = _get_cmd_syntax(name, cmd) syntax = _get_cmd_syntax(name, cmd)
if syntax != name: if syntax != name:
output.append('Syntax: +:{}+'.format(syntax)) output.append('Syntax: +:{}+'.format(syntax))
output.append("") output.append("")
parser = utils.DocstringParser(cmd.handler) parser = utils.DocstringParser(cmd.handler)
output.append(parser.short_desc) output.append(parser.short_desc)
output.append("") if parser.long_desc:
output.append(parser.long_desc) output.append("")
output.append(parser.long_desc)
if parser.arg_descs: if parser.arg_descs:
output.append("") output.append("")
for arg, desc in parser.arg_descs.items(): for arg, desc in parser.arg_descs.items():
@ -104,7 +161,7 @@ def _get_command_doc(name, cmd):
item = "* +{}+: {}".format(arg, firstline) item = "* +{}+: {}".format(arg, firstline)
item += '\n'.join(text[1:]) item += '\n'.join(text[1:])
output.append(item) output.append(item)
output.append("") output.append("")
output.append("") output.append("")
return '\n'.join(output) return '\n'.join(output)
@ -154,80 +211,83 @@ def _format_action(action):
return '{}\n {}\n'.format(invocation, action.help) return '{}\n {}\n'.format(invocation, action.help)
def generate_commands(f): def generate_commands(filename):
"""Generate the complete commands section.""" """Generate the complete commands section."""
f.write('\n') with _open_file(filename) as f:
f.write("== COMMANDS\n") f.write('\n')
normal_cmds = [] f.write("== COMMANDS\n")
hidden_cmds = [] normal_cmds = []
debug_cmds = [] hidden_cmds = []
for name, cmd in cmdutils.cmd_dict.items(): debug_cmds = []
if cmd.hide: for name, cmd in cmdutils.cmd_dict.items():
hidden_cmds.append((name, cmd)) if cmd.hide:
elif cmd.debug: hidden_cmds.append((name, cmd))
debug_cmds.append((name, cmd)) elif cmd.debug:
else: debug_cmds.append((name, cmd))
normal_cmds.append((name, cmd)) else:
normal_cmds.sort() normal_cmds.append((name, cmd))
hidden_cmds.sort() normal_cmds.sort()
debug_cmds.sort() hidden_cmds.sort()
f.write("\n") debug_cmds.sort()
f.write("=== Normal commands\n")
f.write(".Quick reference\n")
f.write(_get_command_quickref(normal_cmds) + "\n")
for name, cmd in normal_cmds:
f.write(_get_command_doc(name, cmd) + "\n")
f.write("\n")
f.write("=== Hidden commands\n")
f.write(".Quick reference\n")
f.write(_get_command_quickref(hidden_cmds) + "\n")
for name, cmd in hidden_cmds:
f.write(_get_command_doc(name, cmd) + "\n")
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")
f.write("\n")
f.write(".Quick reference\n")
f.write(_get_command_quickref(debug_cmds) + "\n")
for name, cmd in debug_cmds:
f.write(_get_command_doc(name, cmd) + "\n")
def generate_settings(f):
"""Generate the complete settings section."""
f.write("\n")
f.write("== SETTINGS\n")
f.write(_get_setting_quickref() + "\n")
for sectname, sect in configdata.DATA.items():
f.write("\n") f.write("\n")
f.write("=== {}".format(sectname) + "\n") f.write("=== Normal commands\n")
f.write(configdata.SECTION_DESC[sectname] + "\n") f.write(".Quick reference\n")
if not getattr(sect, 'descriptions'): f.write(_get_command_quickref(normal_cmds) + "\n\n")
pass for name, cmd in normal_cmds:
else: f.write(_get_command_doc(name, cmd))
for optname, option in sect.items(): f.write("\n")
f.write("\n") f.write("=== Hidden commands\n")
f.write('[[setting-{}-{}]]'.format(sectname, optname) + "\n") f.write(".Quick reference\n")
f.write("==== {}".format(optname) + "\n") f.write(_get_command_quickref(hidden_cmds))
f.write(sect.descriptions[optname] + "\n") for name, cmd in hidden_cmds:
f.write("\n") f.write(_get_command_doc(name, cmd))
valid_values = option.typ.valid_values f.write("\n")
if valid_values is not None: f.write("=== Debugging commands\n")
f.write("Valid values:\n") f.write("These commands are mainly intended for debugging. They are "
"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))
for name, cmd in debug_cmds:
f.write(_get_command_doc(name, cmd))
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")
for sectname, sect in configdata.DATA.items():
f.write("\n")
f.write("=== {}".format(sectname) + "\n")
f.write(configdata.SECTION_DESC[sectname] + "\n")
if not getattr(sect, 'descriptions'):
pass
else:
for optname, option in sect.items():
f.write("\n") f.write("\n")
for val in valid_values: f.write('[[{}-{}]]'.format(sectname, optname) + "\n")
try: f.write("==== {}".format(optname) + "\n")
desc = valid_values.descriptions[val] f.write(sect.descriptions[optname] + "\n")
f.write(" * +{}+: {}".format(val, desc) + "\n")
except KeyError:
f.write(" * +{}+".format(val) + "\n")
f.write("\n") f.write("\n")
if option.default(): valid_values = option.typ.valid_values
f.write("Default: +pass:[{}]+\n".format(html.escape( if valid_values is not None:
option.default()))) f.write("Valid values:\n")
else: f.write("\n")
f.write("Default: empty\n") for val in valid_values:
try:
desc = valid_values.descriptions[val]
f.write(" * +{}+: {}".format(val, desc) + "\n")
except KeyError:
f.write(" * +{}+".format(val) + "\n")
f.write("\n")
if option.default():
f.write("Default: +pass:[{}]+\n".format(html.escape(
option.default())))
else:
f.write("Default: empty\n")
def _get_authors(): def _get_authors():
@ -312,6 +372,6 @@ def regenerate_manpage(filename):
if __name__ == '__main__': if __name__ == '__main__':
regenerate_manpage('doc/qutebrowser.1.asciidoc') 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') regenerate_authors('README.asciidoc')