From ab8f487b506392ef6c60d56b43deab1b0f6bb82d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Thu, 5 Sep 2019 22:55:20 +0200 Subject: [PATCH 1/3] Fix Sphinx 2 new API for Fedora 31+ QubesOS/qubes-issues#5289 --- doc/skel-manpage.py | 7 +++++-- qubesadmin/tools/dochelpers.py | 27 ++++++++++++++------------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/doc/skel-manpage.py b/doc/skel-manpage.py index 14ddfa7..bd71bea 100755 --- a/doc/skel-manpage.py +++ b/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 qubesadmin.tools.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 ' - 'qubesadmin.tools.') + help='program\'s command name; this should translate to ' + 'qubesadmin.tools.') + def main(): args = parser.parse_args() sys.stdout.write(qubesadmin.tools.dochelpers.prepare_manpage(args.command)) + if __name__ == '__main__': main() diff --git a/qubesadmin/tools/dochelpers.py b/qubesadmin/tools/dochelpers.py index 6b0f949..4dd7e2c 100644 --- a/qubesadmin/tools/dochelpers.py +++ b/qubesadmin/tools/dochelpers.py @@ -39,9 +39,12 @@ import sphinx import sphinx.errors import sphinx.locale import sphinx.util.docfields +from sphinx.util import logging import qubesadmin.tools +log = logging.getLogger(__name__) + SUBCOMMANDS_TITLE = 'COMMANDS' OPTIONS_TITLE = 'OPTIONS' @@ -79,14 +82,13 @@ 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))) + stream.write(', '.join( + '{}{}{}'.format(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)) @@ -107,6 +109,7 @@ def prepare_manpage(command): class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): ''' 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) @@ -119,7 +122,6 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): 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` ''' if not isinstance(node[0], docutils.nodes.Text): @@ -198,7 +200,6 @@ 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. @@ -218,12 +219,13 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): ''' 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: parser = qubesadmin.tools.get_parser_for_command(command) except ImportError: - app.warn('cannot import module for command') + log.warning('cannot import module for command') self.parser = None return except AttributeError: @@ -261,7 +263,7 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): 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: @@ -270,6 +272,7 @@ 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 options. @@ -278,11 +281,10 @@ def check_man_args(app, doctree, docname): if os.path.basename(dirname) != 'manpages': return - app.info('Checking arguments for {!r}'.format(command)) + log.info('Checking arguments for {!r}'.format(command)) doctree.walk(ManpageCheckVisitor(app, command, doctree)) - def break_to_pdb(app, *_dummy): '''DEBUG''' if not app.config.break_to_pdb: @@ -298,5 +300,4 @@ def setup(app): app.connect('doctree-resolved', break_to_pdb) app.connect('doctree-resolved', check_man_args) - # vim: ts=4 sw=4 et From 6df676c259e67a20e88b5bc48800c91245213c27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 6 Sep 2019 16:20:54 +0200 Subject: [PATCH 2/3] dochelpers: handle legacy sphinx library --- qubesadmin/tools/dochelpers.py | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/qubesadmin/tools/dochelpers.py b/qubesadmin/tools/dochelpers.py index 4dd7e2c..805910d 100644 --- a/qubesadmin/tools/dochelpers.py +++ b/qubesadmin/tools/dochelpers.py @@ -43,7 +43,10 @@ from sphinx.util import logging import qubesadmin.tools -log = logging.getLogger(__name__) +try: + log = logging.getLogger(__name__) +except AttributeError: + log = None SUBCOMMANDS_TITLE = 'COMMANDS' OPTIONS_TITLE = 'OPTIONS' @@ -225,7 +228,13 @@ class ManpageCheckVisitor(docutils.nodes.SparseNodeVisitor): try: parser = qubesadmin.tools.get_parser_for_command(command) except ImportError: - log.warning('cannot import module for command') + msg = 'cannot import module for command' + if log: + log.warning(msg) + else: + # Handle legacy + app.warn(msg) + self.parser = None return except AttributeError: @@ -281,7 +290,12 @@ def check_man_args(app, doctree, docname): if os.path.basename(dirname) != 'manpages': return - log.info('Checking arguments for {!r}'.format(command)) + msg = 'Checking arguments for {!r}'.format(command) + if log: + log.info(msg) + else: + # Handle legacy + app.info(msg) doctree.walk(ManpageCheckVisitor(app, command, doctree)) From 3ddeb2046a395df4c1196133ef31ab47837854ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Pierret=20=28fepitre=29?= Date: Fri, 6 Sep 2019 16:26:51 +0200 Subject: [PATCH 3/3] dochelpers: make PEP8 happier --- qubesadmin/tools/dochelpers.py | 60 +++++++++++++++++----------------- 1 file changed, 30 insertions(+), 30 deletions(-) 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)