|
@@ -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 <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)
|
|
@@ -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)
|