diff --git a/qubesadmin/tools/dochelpers.py b/qubesadmin/tools/dochelpers.py index 805910d..f8641b3 100644 --- a/qubesadmin/tools/dochelpers.py +++ b/qubesadmin/tools/dochelpers.py @@ -19,11 +19,11 @@ # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. # -'''Documentation helpers. +"""Documentation helpers. This module contains classes and functions which help to maintain documentation, particularly our custom Sphinx extension. -''' +""" import argparse import io @@ -53,25 +53,25 @@ OPTIONS_TITLE = 'OPTIONS' def make_rst_section(heading, char): - '''Format a section header in rst''' + """Format a section header in rst""" return '{}\n{}\n\n'.format(heading, char[0] * len(heading)) def prepare_manpage(command): - '''Build a man page skeleton''' + """Build a man page skeleton""" parser = qubesadmin.tools.get_parser_for_command(command) stream = io.StringIO() 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()) @@ -97,21 +97,21 @@ def prepare_manpage(command): stream.write('\n\n {}\n\n'.format(action.help)) stream.write(make_rst_section('Authors', '-')) - stream.write('''\ + stream.write("""\ | Joanna Rutkowska | Rafal Wojtczuk | Marek Marczykowski | Wojtek Porczyk .. 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) @@ -120,13 +120,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') @@ -138,14 +138,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 @@ -156,9 +156,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) @@ -166,12 +166,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: @@ -191,10 +191,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:'): @@ -204,14 +204,14 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): 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( @@ -219,9 +219,9 @@ 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) @@ -263,9 +263,9 @@ 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 @@ -283,9 +283,9 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): 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 @@ -300,7 +300,7 @@ def check_man_args(app, doctree, docname): def break_to_pdb(app, *_dummy): - '''DEBUG''' + """DEBUG""" if not app.config.break_to_pdb: return import pdb @@ -308,7 +308,7 @@ def break_to_pdb(app, *_dummy): def setup(app): - '''Setup Sphinx extension''' + """Setup Sphinx extension""" app.add_config_value('break_to_pdb', False, 'env') app.connect('doctree-resolved', break_to_pdb)