From eaed493f855c653221f98c8f69a4ba0d76c954f7 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Thu, 24 Jul 2014 01:51:23 +0200 Subject: [PATCH] More manpage improvments --- scripts/generate_doc.py | 97 +++++++++++++++++++++++++++++++++++------ 1 file changed, 84 insertions(+), 13 deletions(-) diff --git a/scripts/generate_doc.py b/scripts/generate_doc.py index 410fa54ab..a6d9989d1 100644 --- a/scripts/generate_doc.py +++ b/scripts/generate_doc.py @@ -25,7 +25,6 @@ import inspect import subprocess from collections import Counter from tempfile import mkstemp -from argparse import RawTextHelpFormatter sys.path.insert(0, os.getcwd()) @@ -233,8 +232,11 @@ def _format_action(action): def generate_manpage_header(f): """Generate an asciidoc header for the manpage.""" + f.write("// DO NOT EDIT THIS FILE BY HAND!\n") + f.write("// It is generated by `scripts/generate_doc.py`.\n") + f.write("// Most likely you'll need to rerun that script, or edit that " + "instead of this file.\n") f.write('= qutebrowser(1)\n') - f.write('Florian Bruhin \n') f.write(':doctype: manpage\n') f.write(':man source: qutebrowser\n') f.write(':man manual: qutebrowser manpage\n') @@ -257,18 +259,27 @@ def generate_manpage_synopsis(f): "['URL' ['...']]\n") f.write('\n') + +def generate_manpage_description(f): + f.write('== DESCRIPTION\n') + f.write("qutebrowser is a keyboard-focused browser with with a minimal " + "GUI. It's based on Python, PyQt5 and QtWebKit and free software, " + "licensed under the GPL.\n\n") + f.write("It was inspired by other browsers/addons like dwb and " + "Vimperator/Pentadactyl.\n\n") + + def generate_manpage_options(f): """Generate the OPTIONS-section of the manpage from an argparse parser.""" parser = qutequtebrowser.get_argparser() - formatter = RawTextHelpFormatter('qutebrowser') f.write('== OPTIONS\n') # positionals, optionals and user-defined groups - for action_group in parser._action_groups: - f.write('=== {}\n'.format(action_group.title)) - if action_group.description is not None: - f.write(action_group.description + '\n') - for action in action_group._group_actions: + for group in parser._action_groups: # pylint: disable=protected-access + f.write('=== {}\n'.format(group.title)) + if group.description is not None: + f.write(group.description + '\n') + for action in group._group_actions: # pylint: disable=protected-access f.write(_format_action(action)) f.write('\n') # epilog @@ -276,10 +287,11 @@ def generate_manpage_options(f): f.write(parser.epilog) f.write('\n') + def generate_commands(f): """Generate the complete commands section.""" f.write('\n') - f.write("== Commands\n") + f.write("== COMMANDS\n") normal_cmds = [] hidden_cmds = [] debug_cmds = [] @@ -319,7 +331,7 @@ def generate_commands(f): def generate_settings(f): """Generate the complete settings section.""" f.write("\n") - f.write("== Settings\n") + f.write("== SETTINGS\n") f.write(_get_setting_quickref() + "\n") for sectname, sect in configdata.DATA.items(): f.write("\n") @@ -352,10 +364,64 @@ def generate_settings(f): f.write("Default: empty\n") -def regenerate_authors(filename): - """Re-generate the authors inside README based on the commits made.""" +def _get_authors(): + """Get a list of authors based on git commit logs.""" commits = subprocess.check_output(['git', 'log', '--format=%aN']) cnt = Counter(commits.decode('utf-8').splitlines()) + return sorted(cnt, key=lambda k: cnt[k]) + + +def generate_manpage_author(f): + """Generate the manpage AUTHOR section.""" + f.write("== AUTHOR\n") + f.write("Contributors, sorted by the number of commits in descending " + "order:\n\n") + for author in _get_authors(): + f.write('* {}\n'.format(author)) + f.write('\n') + + +def generate_manpage_bugs(f): + """Generate the manpage BUGS section.""" + f.write('== BUGS\n') + f.write("Bugs are tracked at two locations:\n\n") + f.write("* The link:BUGS[doc/BUGS] and link:TODO[doc/TODO] files shipped " + "with qutebrowser.\n") + f.write("* The Github issue tracker at https://github.com/The-Compiler/" + "qutebrowser/issues .\n\n") + f.write("If you found a bug or have a suggestion, either open a ticket " + "in the github issue tracker, or write a mail to the " + "https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser[" + "mailinglist] at mailto:qutebrowser@lists.qutebrowser.org[].\n\n") + + +def generate_manpage_copyright(f): + f.write('== COPYRIGHT\n') + f.write("This program 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.\n\n") + f.write("This program 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.\n\n") + f.write("You should have received a copy of the GNU General Public " + "License along with this program. If not, see " + ".\n") + + +def generate_manpage_resources(f): + f.write('== RESOURCES\n\n') + f.write("* Website: http://www.qutebrowser.org/\n") + f.write("* Mailinglist: mailto:qutebrowser@lists.qutebrowser.org[] / " + "https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser\n") + f.write("* IRC: irc://irc.freenode.org/#qutebrowser[`#qutebrowser`] on " + "http://freenode.net/[Freenode]\n") + f.write("* Github: https://github.com/The-Compiler/qutebrowser\n\n") + + +def regenerate_authors(filename): + """Re-generate the authors inside README based on the commits made.""" oshandle, tmpname = mkstemp() with _open_file(filename, mode='r') as infile, \ _open_file(oshandle, mode='w') as temp: @@ -364,7 +430,7 @@ def regenerate_authors(filename): if line.strip() == '// QUTE_AUTHORS_START': ignore = True temp.write(line) - for author in sorted(cnt, key=lambda k: cnt[k]): + for author in _get_authors(): temp.write('* {}\n'.format(author)) elif line.strip() == '// QUTE_AUTHORS_END': temp.write(line) @@ -380,7 +446,12 @@ if __name__ == '__main__': generate_manpage_header(fobj) generate_manpage_name(fobj) generate_manpage_synopsis(fobj) + generate_manpage_description(fobj) generate_manpage_options(fobj) generate_settings(fobj) generate_commands(fobj) + generate_manpage_bugs(fobj) + generate_manpage_author(fobj) + generate_manpage_resources(fobj) + generate_manpage_copyright(fobj) regenerate_authors('README.asciidoc')