Start rewriting manpage generation

.gitignore

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

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.

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):
+def _format_block(filename, what, data):
-    """Generate the manpage AUTHOR section."""
+    """Format a block in a file.
-    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')
 
+    The block is delimited by markers like these:
+        // QUTE_*_START
+        ...
+        // QUTE_*_END
 
-def generate_manpage_bugs(f):
+    The * part is the part which should be given as 'what'.
-    """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")
 
-
+    Args:
-def generate_manpage_copyright(f):
+        filename: The file to change.
-    """Generate the COPYRIGHT section of the manpage."""
+        what: What to change (authors, options, etc.)
-    f.write('== COPYRIGHT\n')
+        data; A list of strings which is the new data.
-    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 "
+    what = what.upper()
-            "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")
-
-
-def regenerate_authors(filename):
-    """Re-generate the authors inside README based on the commits made."""
     oshandle, tmpname = tempfile.mkstemp()
+    try:
         with _open_file(filename, mode='r') as infile, \
                 _open_file(oshandle, mode='w') as temp:
-        ignore = False
+            found_start = False
+            found_end = False
             for line in infile:
-            if line.strip() == '// QUTE_AUTHORS_START':
+                if line.strip() == '// QUTE_{}_START'.format(what):
-                ignore = True
                     temp.write(line)
-                for author in _get_authors():
+                    temp.write(''.join(data))
-                    temp.write('* {}\n'.format(author))
+                    found_start = True
-            elif line.strip() == '// QUTE_AUTHORS_END':
+                elif line.strip() == '// QUTE_{}_END'.format(what.upper()):
                     temp.write(line)
-                ignore = False
+                    found_end = True
-            elif not ignore:
+                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."""
+    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:
+    regenerate_manpage('doc/qutebrowser.1.asciidoc')
-        generate_manpage_header(fobj)
+    #generate_settings(fobj)
-        generate_manpage_name(fobj)
+    #generate_commands(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')