More manpage improvments

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 <mail@qutebrowser.org>\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:
+    for group in parser._action_groups:  # pylint: disable=protected-access
-        f.write('=== {}\n'.format(action_group.title))
+        f.write('=== {}\n'.format(group.title))
-        if action_group.description is not None:
+        if group.description is not None:
-            f.write(action_group.description + '\n')
+            f.write(group.description + '\n')
-        for action in action_group._group_actions:
+        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):
+def _get_authors():
-    """Re-generate the authors inside README based on the commits made."""
+    """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 "
+            "<http://www.gnu.org/licenses/>.\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')