doc: Make PEP8 happier

doc/skel-manpage.py

@@ -2,6 +2,7 @@
 
 import os
 import sys
+
 sys.path.insert(0, os.path.abspath('../'))
 
 import argparse
@@ -9,12 +10,14 @@ import qubes.dochelpers
 
 parser = argparse.ArgumentParser(description='prepare new manpage for command')
 parser.add_argument('command', metavar='COMMAND',
-    help='program\'s command name; this should translate to '
-        'qubes.tools.<command_name>')
+                    help='program\'s command name; this should translate to '
+                         'qubes.tools.<command_name>')
+
 
 def main():
     args = parser.parse_args()
     sys.stdout.write(qubes.dochelpers.prepare_manpage(args.command))
 
+
 if __name__ == '__main__':
     main()

qubes/dochelpers.py

@@ -18,11 +18,11 @@
 # License along with this library; if not, see <https://www.gnu.org/licenses/>.
 #
 
-'''Documentation helpers.
+"""Documentation helpers.
 
 This module contains classes and functions which help to maintain documentation,
 particularly our custom Sphinx extension.
-'''
+"""
 
 import argparse
 import io
@@ -55,14 +55,15 @@ class GithubTicket:
         self.summary = data['title']
         self.uri = data['html_url']
 
+
 def fetch_ticket_info(app, number):
-    '''Fetch info about particular trac ticket given
+    """Fetch info about particular trac ticket given
 
     :param app: Sphinx app object
     :param str number: number of the ticket, without #
     :rtype: mapping
     :raises: urllib.error.HTTPError
-    '''
+    """
 
     response = urllib.request.urlopen(urllib.request.Request(
         app.config.ticket_base_uri.format(number=number),
@@ -71,8 +72,9 @@ def fetch_ticket_info(app, number):
             'User-agent': __name__}))
     return GithubTicket(json.load(response))
 
+
 def ticket(name, rawtext, text, lineno, inliner, options=None, content=None):
-    '''Link to qubes ticket
+    """Link to qubes ticket
 
     :param str name: The role name used in the document
     :param str rawtext: The entire markup snippet, with role
@@ -82,7 +84,7 @@ def ticket(name, rawtext, text, lineno, inliner, options=None, content=None):
         that called this function
     :param options: Directive options for customisation
     :param content: The directive content for customisation
-    ''' # pylint: disable=unused-argument
+    """  # pylint: disable=unused-argument
 
     if options is None:
         options = {}
@@ -117,20 +119,23 @@ class versioncheck(docutils.nodes.warning):
     # pylint: disable=invalid-name
     pass
 
+
 def visit(self, node):
     self.visit_admonition(node, 'version')
 
+
 def depart(self, node):
     self.depart_admonition(node)
 
+
 sphinx.locale.admonitionlabels['version'] = 'Version mismatch'
 
 
 class VersionCheck(docutils.parsers.rst.Directive):
-    '''Directive versioncheck
+    """Directive versioncheck
 
     Check if current version (from ``conf.py``) equals version specified as
-    argument. If not, generate warning.'''
+    argument. If not, generate warning."""
 
     has_content = True
     required_arguments = 1
@@ -145,16 +150,16 @@ class VersionCheck(docutils.parsers.rst.Directive):
         if current == version:
             return []
 
-        text = ' '.join('''This manual page was written for version **{}**, but
+        text = ' '.join("""This manual page was written for version **{}**, but
             current version at the time when this page was generated is **{}**.
             This may or may not mean that page is outdated or has
-            inconsistencies.'''.format(version, current).split())
+            inconsistencies.""".format(version, current).split())
 
         node = versioncheck(text)
         node['classes'] = ['admonition', 'warning']
 
         self.state.nested_parse(docutils.statemachine.StringList([text]),
-            self.content_offset, node)
+                                self.content_offset, node)
         return [node]
 
 
@@ -168,14 +173,14 @@ def prepare_manpage(command):
     stream.write('.. program:: {}\n\n'.format(command))
     stream.write(make_rst_section(
         ':program:`{}` -- {}'.format(command, parser.description), '='))
-    stream.write('''.. warning::
+    stream.write(""".. warning::
 
    This page was autogenerated from command-line parser. It shouldn't be 1:1
    conversion, because it would add little value. Please revise it and add
    more descriptive help, which normally won't fit in standard ``--help``
    option.
 
-   After rewrite, please remove this admonition.\n\n''')
+   After rewrite, please remove this admonition.\n\n""")
 
     stream.write(make_rst_section('Synopsis', '-'))
     usage = ' '.join(parser.format_usage().strip().split())
@@ -189,34 +194,35 @@ def prepare_manpage(command):
 
     stream.write(make_rst_section('Options', '-'))
 
-    for action in parser._actions: # pylint: disable=protected-access
+    for action in parser._actions:  # pylint: disable=protected-access
         stream.write('.. option:: ')
         if action.metavar:
             stream.write(', '.join('{}{}{}'.format(
-                    option,
-                    '=' if option.startswith('--') else ' ',
-                    action.metavar)
-                for option in sorted(action.option_strings)))
+                option,
+                '=' if option.startswith('--') else ' ',
+                action.metavar)
+                                   for option in sorted(action.option_strings)))
         else:
             stream.write(', '.join(sorted(action.option_strings)))
         stream.write('\n\n   {}\n\n'.format(action.help))
 
     stream.write(make_rst_section('Authors', '-'))
-    stream.write('''\
+    stream.write("""\
 | Joanna Rutkowska <joanna at invisiblethingslab dot com>
 | Rafal Wojtczuk <rafal at invisiblethingslab dot com>
 | Marek Marczykowski <marmarek at invisiblethingslab dot com>
 | Wojtek Porczyk <woju at invisiblethingslab dot com>
 
 .. vim: ts=3 sw=3 et tw=80
-''')
+""")
 
     return stream.getvalue()
 
 
 class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor):
-    ''' Checks if the visited option nodes and the specified args are in sync.
-    '''
+    """ Checks if the visited option nodes and the specified args are in sync.
+    """
+
     def __init__(self, command, args, document):
         assert isinstance(args, set)
         docutils.nodes.SparseNodeVisitor.__init__(self, document)
@@ -224,14 +230,13 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor):
         self.args = args
 
     def visit_desc(self, node):
-        ''' Skips all but 'option' elements '''
+        """ Skips all but 'option' elements """
         # pylint: disable=no-self-use
         if not node.get('desctype', None) == 'option':
             raise docutils.nodes.SkipChildren
 
-
     def visit_desc_name(self, node):
-        ''' Checks if the option is defined `self.args` '''
+        """ Checks if the option is defined `self.args` """
         if not isinstance(node[0], docutils.nodes.Text):
             raise sphinx.errors.SphinxError('first child should be Text')
 
@@ -243,14 +248,14 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor):
                 'No such argument for {!r}: {!r}'.format(self.command, arg))
 
     def check_undocumented_arguments(self, ignored_options=None):
-        ''' Call this to check if any undocumented arguments are left.
+        """ Call this to check if any undocumented arguments are left.
 
             While the documentation talks about a
             'SparseNodeVisitor.depart_document()' function, this function does
             not exists. (For details see implementation of
             :py:meth:`NodeVisitor.dispatch_departure()`) So we need to
             manually call this.
-        '''
+        """
         if ignored_options is None:
             ignored_options = set()
         left_over_args = self.args - ignored_options
@@ -261,9 +266,9 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor):
 
 
 class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
-    ''' Checks if the visited sub command section nodes and the specified sub
+    """ Checks if the visited sub command section nodes and the specified sub
         command args are in sync.
-    '''
+    """
 
     def __init__(self, command, sub_commands, document):
         docutils.nodes.SparseNodeVisitor.__init__(self, document)
@@ -271,12 +276,12 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
         self.sub_commands = sub_commands
 
     def visit_section(self, node):
-        ''' Checks if the visited sub-command section nodes exists and it
+        """ Checks if the visited sub-command section nodes exists and it
             options are in sync.
 
             Uses :py:class:`OptionsCheckVisitor` for checking
             sub-commands options
-        '''
+        """
         # pylint: disable=no-self-use
         title = str(node[0][0])
         if title.upper() == SUBCOMMANDS_TITLE:
@@ -296,10 +301,10 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
                 'No such sub-command {!r}'.format(sub_cmd))
 
     def visit_Text(self, node):
-        ''' If the visited text node starts with 'alias: ', all the provided
+        """ If the visited text node starts with 'alias: ', all the provided
             comma separted alias in this node, are removed from
             `self.sub_commands`
-        '''
+        """
         # pylint: disable=invalid-name
         text = str(node).strip()
         if text.startswith('aliases:'):
@@ -308,16 +313,15 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
                 assert alias in self.sub_commands
                 del self.sub_commands[alias]
 
-
     def check_undocumented_sub_commands(self):
-        ''' Call this to check if any undocumented sub_commands are left.
+        """ Call this to check if any undocumented sub_commands are left.
 
             While the documentation talks about a
             'SparseNodeVisitor.depart_document()' function, this function does
             not exists. (For details see implementation of
             :py:meth:`NodeVisitor.dispatch_departure()`) So we need to
             manually call this.
-        '''
+        """
         if self.sub_commands:
             raise sphinx.errors.SphinxError(
                 'Undocumented commands for {!r}: {!r}'.format(
@@ -325,9 +329,10 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor):
 
 
 class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor):
-    ''' Checks if the sub-commands and options specified in the 'COMMAND' and
+    """ Checks if the sub-commands and options specified in the 'COMMAND' and
         'OPTIONS' (case insensitve) sections in sync the command parser.
-    '''
+    """
+
     def __init__(self, app, command, document):
         docutils.nodes.SparseNodeVisitor.__init__(self, document)
         try:
@@ -362,16 +367,16 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor):
                 self.options.update(action.option_strings)
 
     def visit_section(self, node):
-        ''' If section title is OPTIONS or COMMANDS dispatch the apropriate
+        """ If section title is OPTIONS or COMMANDS dispatch the apropriate
             `NodeVisitor`.
-        '''
+        """
         if self.parser is None:
             return
 
         section_title = str(node[0][0]).upper()
         if section_title == OPTIONS_TITLE:
             options_visitor = OptionsCheckVisitor(self.command, self.options,
-                                          self.document)
+                                                  self.document)
             node.walkabout(options_visitor)
             options_visitor.check_undocumented_arguments()
         elif section_title == SUBCOMMANDS_TITLE:
@@ -380,10 +385,11 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor):
             node.walkabout(sub_cmd_visitor)
             sub_cmd_visitor.check_undocumented_sub_commands()
 
+
 def check_man_args(app, doctree, docname):
-    ''' Checks the manpage for undocumented or obsolete sub-commands and
+    """ Checks the manpage for undocumented or obsolete sub-commands and
         options.
-    '''
+    """
     dirname, command = os.path.split(docname)
     if os.path.basename(dirname) != 'manpages':
         return
@@ -398,6 +404,7 @@ def check_man_args(app, doctree, docname):
 
 event_sig_re = re.compile(r'([a-zA-Z-:<>]+)\s*\((.*)\)')
 
+
 def parse_event(env, sig, signode):
     # pylint: disable=unused-argument
     m = event_sig_re.match(sig)
@@ -413,6 +420,7 @@ def parse_event(env, sig, signode):
     signode += plist
     return name
 
+
 #
 # end of codelifting
 #
@@ -433,17 +441,17 @@ def setup(app):
         'env')
     app.add_config_value('break_to_pdb', False, 'env')
     app.add_node(versioncheck,
-        html=(visit, depart),
-        man=(visit, depart))
+                 html=(visit, depart),
+                 man=(visit, depart))
     app.add_directive('versioncheck', VersionCheck)
 
     fdesc = sphinx.util.docfields.GroupedField('parameter', label='Parameters',
-                         names=['param'], can_collapse=True)
+                                               names=['param'],
+                                               can_collapse=True)
     app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
                         doc_field_types=[fdesc])
 
     app.connect('doctree-resolved', break_to_pdb)
     app.connect('doctree-resolved', check_man_args)
 
-
 # vim: ts=4 sw=4 et