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

Adjust generate_manpage to generate other docs as well

Browse Source
This commit is contained in:
Florian Bruhin 2014-07-16 22:26:00 +02:00
parent 2bbd687430
commit c1128a16a2
3 changed files with 93 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.asciidoc
View File

@ -91,7 +91,11 @@ Note a standalone .exe is available.
Authors Authors
------- -------
include::doc/AUTHORS.asciidoc[] Contributors, sorted by the number of commits in descending order:
// QUTE_AUTHORS_START
* Florian Bruhin
// QUTE_AUTHORS_END
Thanks / Similiar projects Thanks / Similiar projects
-------------------------- --------------------------

35
scripts/generate_authors.py
View File

@ -1,35 +0,0 @@
#!/usr/bin/python
# vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
# Copyright 2014 Florian Bruhin (The Compiler) <mail@qutebrowser.org>
#
# This file is part of qutebrowser.
#
# qutebrowser is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# qutebrowser is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with qutebrowser. If not, see <http://www.gnu.org/licenses/>.
"""Re-generate the AUTHORS file based on the commits made."""
import subprocess
from collections import Counter
commits = subprocess.check_output(['git', 'log', '--format=%aN'])
cnt = Counter(commits.decode('utf-8').splitlines())
with open('doc/AUTHORS.asciidoc', 'w', newline='\n', encoding='utf-8') as f:
f.write("Contributors, sorted by the number of commits in descending "
"order:\n\n")
for author in sorted(cnt, key=lambda k: cnt[k]):
f.write('* ' + author)
f.write('\n')

144
scripts/generate_manpage.py
View File

@ -20,7 +20,11 @@
import os import os
import sys import sys
import cgi import cgi
import shutil
import inspect import inspect
import subprocess
from collections import Counter
from tempfile import mkstemp
sys.path.insert(0, os.getcwd()) sys.path.insert(0, os.getcwd())
@ -29,8 +33,11 @@ import qutebrowser.commands.utils as cmdutils
import qutebrowser.config.configdata as configdata import qutebrowser.config.configdata as configdata
from qutebrowser.utils.usertypes import enum from qutebrowser.utils.usertypes import enum
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 parse_docstring(func): def _parse_docstring(func):
"""Generates documentation based on a docstring of a command handler. """Generates documentation based on a docstring of a command handler.
The docstring needs to follow the format described in HACKING. The docstring needs to follow the format described in HACKING.
@ -94,7 +101,7 @@ def parse_docstring(func):
return (short_desc, long_desc, arg_descs) return (short_desc, long_desc, arg_descs)
def get_cmd_syntax(name, cmd): def _get_cmd_syntax(name, cmd):
words = [] words = []
argspec = inspect.getfullargspec(cmd.handler) argspec = inspect.getfullargspec(cmd.handler)
if argspec.defaults is not None: if argspec.defaults is not None:
@ -115,7 +122,7 @@ def get_cmd_syntax(name, cmd):
return (' '.join(words), defaults) return (' '.join(words), defaults)
def get_command_quickref(cmds): def _get_command_quickref(cmds):
out = [] out = []
out.append('[options="header",width="75%",cols="25%,75%"]') out.append('[options="header",width="75%",cols="25%,75%"]')
out.append('|==============') out.append('|==============')
@ -127,7 +134,7 @@ def get_command_quickref(cmds):
return '\n'.join(out) return '\n'.join(out)
def get_setting_quickref(): def _get_setting_quickref():
out = [] out = []
for sectname, sect in configdata.DATA.items(): for sectname, sect in configdata.DATA.items():
if not getattr(sect, 'descriptions'): if not getattr(sect, 'descriptions'):
@ -144,13 +151,13 @@ def get_setting_quickref():
return '\n'.join(out) return '\n'.join(out)
def get_command_doc(name, cmd): def _get_command_doc(name, cmd):
output = ['[[cmd-{}]]'.format(name)] output = ['[[cmd-{}]]'.format(name)]
output += ['==== {}'.format(name)] output += ['==== {}'.format(name)]
syntax, defaults = get_cmd_syntax(name, cmd) syntax, defaults = _get_cmd_syntax(name, cmd)
output.append('+:{}+'.format(syntax)) output.append('+:{}+'.format(syntax))
output.append("") output.append("")
short_desc, long_desc, arg_descs = parse_docstring(cmd.handler) short_desc, long_desc, arg_descs = _parse_docstring(cmd.handler)
output.append(' '.join(short_desc)) output.append(' '.join(short_desc))
output.append("") output.append("")
output.append(' '.join(long_desc)) output.append(' '.join(long_desc))
@ -166,17 +173,16 @@ def get_command_doc(name, cmd):
return '\n'.join(output) return '\n'.join(output)
def generate_header(): def generate_header(f):
print('= qutebrowser manpage') f.write('= qutebrowser manpage\n')
print('Florian Bruhin <mail@qutebrowser.org>') f.write('Florian Bruhin <mail@qutebrowser.org>\n')
print(':toc:') f.write(':toc:\n')
print(':homepage: http://www.qutebrowser.org/') f.write(':homepage: http://www.qutebrowser.org/\n')
print("== NAME")
def generate_commands(): def generate_commands(f):
print() f.write('\n')
print("== Commands") f.write("== Commands\n")
normal_cmds = [] normal_cmds = []
hidden_cmds = [] hidden_cmds = []
debug_cmds = [] debug_cmds = []
@ -190,64 +196,90 @@ def generate_commands():
normal_cmds.sort() normal_cmds.sort()
hidden_cmds.sort() hidden_cmds.sort()
debug_cmds.sort() debug_cmds.sort()
print() f.write("\n")
print("=== Normal commands") f.write("=== Normal commands\n")
print(".Quick reference") f.write(".Quick reference\n")
print(get_command_quickref(normal_cmds)) f.write(_get_command_quickref(normal_cmds) + "\n")
for name, cmd in normal_cmds: for name, cmd in normal_cmds:
print(get_command_doc(name, cmd)) f.write(_get_command_doc(name, cmd) + "\n")
print() f.write("\n")
print("=== Hidden commands") f.write("=== Hidden commands\n")
print(".Quick reference") f.write(".Quick reference\n")
print(get_command_quickref(hidden_cmds)) f.write(_get_command_quickref(hidden_cmds) + "\n")
for name, cmd in hidden_cmds: for name, cmd in hidden_cmds:
print(get_command_doc(name, cmd)) f.write(_get_command_doc(name, cmd) + "\n")
print() f.write("\n")
print("=== Debugging commands") f.write("=== Debugging commands\n")
print("These commands are mainly intended for debugging. They are hidden " f.write("These commands are mainly intended for debugging. They are "
"if qutebrowser was started without the `--debug`-flag.") "hidden if qutebrowser was started without the `--debug`-flag.\n")
print() f.write("\n")
print(".Quick reference") f.write(".Quick reference\n")
print(get_command_quickref(debug_cmds)) f.write(_get_command_quickref(debug_cmds) + "\n")
for name, cmd in debug_cmds: for name, cmd in debug_cmds:
print(get_command_doc(name, cmd)) f.write(_get_command_doc(name, cmd) + "\n")
def generate_settings(): def generate_settings(f):
print() f.write("\n")
print("== Settings") f.write("== Settings\n")
print(get_setting_quickref()) f.write(_get_setting_quickref() + "\n")
for sectname, sect in configdata.DATA.items(): for sectname, sect in configdata.DATA.items():
print() f.write("\n")
print("=== {}".format(sectname)) f.write("=== {}".format(sectname) + "\n")
print(configdata.SECTION_DESC[sectname]) f.write(configdata.SECTION_DESC[sectname] + "\n")
if not getattr(sect, 'descriptions'): if not getattr(sect, 'descriptions'):
pass pass
else: else:
for optname, option in sect.items(): for optname, option in sect.items():
print() f.write("\n")
print('[[setting-{}-{}]]'.format(sectname, optname)) f.write('[[setting-{}-{}]]'.format(sectname, optname) + "\n")
print("==== {}".format(optname)) f.write("==== {}".format(optname) + "\n")
print(sect.descriptions[optname]) f.write(sect.descriptions[optname] + "\n")
print() f.write("\n")
valid_values = option.typ.valid_values valid_values = option.typ.valid_values
if valid_values is not None: if valid_values is not None:
print("Valid values:") f.write("Valid values:\n")
print() f.write("\n")
for val in valid_values: for val in valid_values:
try: try:
desc = valid_values.descriptions[val] desc = valid_values.descriptions[val]
print(" * +{}+: {}".format(val, desc)) f.write(" * +{}+: {}".format(val, desc) + "\n")
except KeyError: except KeyError:
print(" * +{}+".format(val)) f.write(" * +{}+".format(val) + "\n")
print() f.write("\n")
if option.default: if option.default:
print("Default: +pass:[{}]+".format(cgi.escape( f.write("Default: +pass:[{}]+\n".format(cgi.escape(
option.default))) option.default)))
else: else:
print("Default: empty") f.write("Default: empty\n")
generate_header() def regenerate_authors(filename):
generate_settings() """Re-generate the authors inside README based on the commits made."""
generate_commands() commits = subprocess.check_output(['git', 'log', '--format=%aN'])
cnt = Counter(commits.decode('utf-8').splitlines())
oshandle, tmpname = mkstemp()
with _open_file(filename, mode='r') as infile, \
_open_file(oshandle, mode='w') as temp:
ignore = False
for line in infile:
if line.strip() == '// QUTE_AUTHORS_START':
ignore = True
temp.write(line)
for author in sorted(cnt, key=lambda k: cnt[k]):
temp.write('* {}\n'.format(author))
elif line.strip() == '// QUTE_AUTHORS_END':
temp.write(line)
ignore = False
elif not ignore:
temp.write(line)
os.remove(filename)
shutil.move(tmpname, filename)
if __name__ == '__main__':
with _open_file('doc/qutebrowser.asciidoc') as f:
generate_header(f)
generate_settings(f)
generate_commands(f)
regenerate_authors('README.asciidoc')