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

Start rewriting manpage generation

Browse Source
This commit is contained in:
Florian Bruhin 2014-09-05 07:45:47 +02:00
parent 6674eedfae
commit a1fabcc5c2
3 changed files with 191 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -11,6 +11,5 @@ __pycache__
/setuptools-*.zip
/qutebrowser/git-commit-id
# We can probably remove these later
*.asciidoc
/doc/*.html
/README.html

125
doc/qutebrowser.1.asciidoc Normal file
View File

@ -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.

201
scripts/generate_doc.py
View File

@ -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")
The * part is the part which should be given as 'what'.
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")
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')