diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | doc/qutebrowser.1.asciidoc | 125 | ||||
| -rwxr-xr-x | scripts/generate_doc.py | 203 |
3 files changed, 192 insertions, 137 deletions
diff --git a/.gitignore b/.gitignore index b0f6073df..6f8b588a7 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,5 @@ __pycache__ /setuptools-*.zip /qutebrowser/git-commit-id # We can probably remove these later -*.asciidoc /doc/*.html /README.html diff --git a/doc/qutebrowser.1.asciidoc b/doc/qutebrowser.1.asciidoc new file mode 100644 index 000000000..bd847fb64 --- /dev/null +++ b/doc/qutebrowser.1.asciidoc @@ -0,0 +1,125 @@ +// Note some sections in this file (everything between QUTE_*_START and +// QUTE_*_END) are autogenerated by scripts/generate_doc.sh. DO NOT edit them +// by hand. + += qutebrowser(1) +:doctype: manpage +:man source: qutebrowser +:man manual: qutebrowser manpage +:toc: +:homepage: http://www.qutebrowser.org/ + +== NAME +qutebrowser - A keyboard-driven, vim-like browser based on PyQt5 and QtWebKit. + +== SYNOPSIS +*qutebrowser* ['-OPTION' ['...']] [':COMMAND' ['...']] ['URL' ['...']] + +== DESCRIPTION +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. + +It was inspired by other browsers/addons like dwb and Vimperator/Pentadactyl. + +== OPTIONS +// QUTE_OPTIONS_START +=== positional arguments +*':command'*:: + Commands to execute on startup. + +*'URL'*:: + URLs to open on startup. + + +=== optional arguments +*-h*, *--help*:: + show this help message and exit + +*-c* 'CONFDIR', *--confdir* 'CONFDIR':: + Set config directory (empty for no config storage) + +*-V*, *--version*:: + Show version and quit. + + +=== debug arguments +*-l* 'LOGLEVEL', *--loglevel* 'LOGLEVEL':: + Set loglevel + +*--logfilter* 'LOGFILTER':: + Comma-separated list of things to be logged to the debug log on stdout. + +*--loglines* 'LOGLINES':: + How many lines of the debug log to keep in RAM (-1: unlimited). + +*--debug*:: + Turn on debugging options. + +*--nocolor*:: + Turn off colored logging. + +*--harfbuzz* '{old,new,system,auto}':: + HarfBuzz engine version to use. Default: auto. + +*--nowindow*:: + Don't show the main window. + +*--debug-exit*:: + Turn on debugging of late exit. + +*--qt-style* 'STYLE':: + Set the Qt GUI style to use. + +*--qt-stylesheet* 'STYLESHEET':: + Override the Qt application stylesheet. + +*--qt-widgetcount*:: + Print debug message at the end about number of widgets left undestroyed and maximum number of widgets existed at the same time. + +*--qt-reverse*:: + Set the application's layout direction to right-to-left. + +*--qt-qmljsdebugger* 'port:PORT[,block]':: + Activate the QML/JS debugger with a specified port. 'block' is optional and will make the application wait until a debugger connects to it. + + + +// QUTE_OPTIONS_END + +== BUGS +Bugs are tracked at two locations: + +* The link:BUGS[doc/BUGS] and link:TODO[doc/TODO] files shipped with +qutebrowser. +* The Github issue tracker at +https://github.com/The-Compiler/qutebrowser/issues. + +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[]. + +== COPYRIGHT +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. + +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. + +You should have received a copy of the GNU General Public License along with +this program. If not, see <http://www.gnu.org/licenses/>. + +== RESOURCES +* Website: http://www.qutebrowser.org/ +* Mailinglist: mailto:qutebrowser@lists.qutebrowser.org[] / +https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser +* IRC: irc://irc.freenode.org/#qutebrowser[`#qutebrowser`] +http://freenode.net/[Freenode] +* Github: https://github.com/The-Compiler/qutebrowser + +== AUTHOR +*qutebrowser* was written by Florian Bruhin. All contributors can be found in +the README file distributed with qutebrowser. diff --git a/scripts/generate_doc.py b/scripts/generate_doc.py index c430d4ff6..87bc6652f 100755 --- a/scripts/generate_doc.py +++ b/scripts/generate_doc.py @@ -154,66 +154,6 @@ def _format_action(action): return '{}\n {}\n\n'.format(invocation, action.help) -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(':doctype: manpage\n') - f.write(':man source: qutebrowser\n') - f.write(':man manual: qutebrowser manpage\n') - f.write(':toc:\n') - f.write(':homepage: http://www.qutebrowser.org/\n') - f.write('\n') - - -def generate_manpage_name(f): - """Generate the NAME-section of the manpage.""" - f.write('== NAME\n') - f.write('qutebrowser - {}\n'.format(qutebrowser.__description__)) - f.write('\n') - - -def generate_manpage_synopsis(f): - """Generate the SYNOPSIS-section of the manpage.""" - f.write('== SYNOPSIS\n') - f.write("*qutebrowser* ['-OPTION' ['...']] [':COMMAND' ['...']] " - "['URL' ['...']]\n") - f.write('\n') - - -def generate_manpage_description(f): - """Generate the DESCRIPTION-section of the manpage.""" - 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.""" - # pylint: disable=protected-access - parser = qutequtebrowser.get_argparser() - f.write('== OPTIONS\n') - - # positionals, optionals and user-defined groups - for group in parser._action_groups: - f.write('=== {}\n'.format(group.title)) - if group.description is not None: - f.write(group.description + '\n') - for action in group._group_actions: - f.write(_format_action(action)) - f.write('\n') - # epilog - if parser.epilog is not None: - f.write(parser.epilog) - f.write('\n') - - def generate_commands(f): """Generate the complete commands section.""" f.write('\n') @@ -297,89 +237,80 @@ def _get_authors(): return reversed(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 _format_block(filename, what, data): + """Format a block in a file. + The block is delimited by markers like these: + // QUTE_*_START + ... + // QUTE_*_END -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): - """Generate the COPYRIGHT section of the manpage.""" - 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 " - "<http://www.gnu.org/licenses/>.\n") - - -def generate_manpage_resources(f): - """Generate the RESOURCES section of the manpage.""" - 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") + The * part is the part which should be given as 'what'. + + Args: + filename: The file to change. + what: What to change (authors, options, etc.) + data; A list of strings which is the new data. + """ + what = what.upper() + oshandle, tmpname = tempfile.mkstemp() + try: + with _open_file(filename, mode='r') as infile, \ + _open_file(oshandle, mode='w') as temp: + found_start = False + found_end = False + for line in infile: + if line.strip() == '// QUTE_{}_START'.format(what): + temp.write(line) + temp.write(''.join(data)) + found_start = True + elif line.strip() == '// QUTE_{}_END'.format(what.upper()): + temp.write(line) + found_end = True + elif (not found_start) or found_end: + temp.write(line) + if not found_start: + raise Exception("Marker '// QUTE_{}_START' not found in " + "'{}'!".format(what, filename)) + elif not found_end: + raise Exception("Marker '// QUTE_{}_END' not found in " + "'{}'!".format(what, filename)) + except: # pylint: disable=bare-except + os.remove(tmpname) + raise + else: + os.remove(filename) + shutil.move(tmpname, filename) def regenerate_authors(filename): """Re-generate the authors inside README based on the commits made.""" - oshandle, tmpname = tempfile.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 _get_authors(): - 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) + data = ['* {}\n'.format(author) for author in _get_authors()] + _format_block(filename, 'authors', data) + + +def regenerate_manpage(filename): + """Update manpage OPTIONS using an argparse parser.""" + # pylint: disable=protected-access + parser = qutequtebrowser.get_argparser() + options = [] + # positionals, optionals and user-defined groups + for group in parser._action_groups: + options.append('=== {}\n'.format(group.title)) + if group.description is not None: + options.append(group.description + '\n') + for action in group._group_actions: + options.append(_format_action(action)) + options.append('\n') + # epilog + if parser.epilog is not None: + options.append(parser.epilog) + options.append('\n') + _format_block(filename, 'options', options) if __name__ == '__main__': - with _open_file('doc/qutebrowser.1.asciidoc') as fobj: - 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_manpage('doc/qutebrowser.1.asciidoc') + #generate_settings(fobj) + #generate_commands(fobj) regenerate_authors('README.asciidoc') |