diff --git a/doc/skel-manpage.py b/doc/skel-manpage.py index c650ebba..11e9a715 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 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.') + help='program\'s command name; this should translate to ' + 'qubes.tools.') + def main(): args = parser.parse_args() sys.stdout.write(qubes.dochelpers.prepare_manpage(args.command)) + if __name__ == '__main__': main() diff --git a/qubes/dochelpers.py b/qubes/dochelpers.py index e55f9317..ee674322 100644 --- a/qubes/dochelpers.py +++ b/qubes/dochelpers.py @@ -18,11 +18,11 @@ # License along with this library; if not, see . # -'''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 | 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) 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