From f393ce62dc6b959e76263de769ec40337969a407 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 27 Jun 2017 02:57:50 +0200 Subject: [PATCH] Fix docstrings formatting Fix warnings/errors reported by Sphinx --- qubes/__init__.py | 4 ++-- qubes/backup.py | 5 +++-- qubes/dochelpers.py | 4 ++-- qubes/tests/__init__.py | 2 +- qubes/tools/__init__.py | 12 +++++++----- qubes/vm/qubesvm.py | 8 ++++---- 6 files changed, 19 insertions(+), 16 deletions(-) diff --git a/qubes/__init__.py b/qubes/__init__.py index 7f933770..8ca58945 100644 --- a/qubes/__init__.py +++ b/qubes/__init__.py @@ -325,8 +325,8 @@ class property(object): # pylint: disable=redefined-builtin,invalid-name setter. Can raise QubesValueError if the value is invalid. :param untrusted_newvalue: value to be validated - :return sanitized value - :raises qubes.exc.QubesValueError + :return: sanitized value + :raises: qubes.exc.QubesValueError ''' # do not treat type='str' as sufficient validation if self.type is not None and self.type is not str: diff --git a/qubes/backup.py b/qubes/backup.py index 1a26221a..e432697e 100644 --- a/qubes/backup.py +++ b/qubes/backup.py @@ -119,6 +119,7 @@ class BackupHeader(object): :param untrusted_header_text: header content :type untrusted_header_text: basestring + .. warning:: This function may be exposed to not yet verified header, so is security critical. @@ -864,9 +865,9 @@ def handle_streams(stream_in, streams_out, processes, size_limit=None, :param processes: dict of subprocess.Popen objects to monitor :param size_limit: int maximum data amount to process :param progress_callback: callable function to report progress, will be - given copied data size (it should accumulate internally) + given copied data size (it should accumulate internally) :return: failed process name, failed stream name, "size_limit" or None ( - no error) + no error) ''' buffer_size = 409600 bytes_copied = 0 diff --git a/qubes/dochelpers.py b/qubes/dochelpers.py index 45ef93c4..2d633830 100644 --- a/qubes/dochelpers.py +++ b/qubes/dochelpers.py @@ -249,7 +249,7 @@ class OptionsCheckVisitor(docutils.nodes.SparseNodeVisitor): While the documentation talks about a 'SparseNodeVisitor.depart_document()' function, this function does not exists. (For details see implementation of - :py:method:`NodeVisitor.dispatch_departure()`) So we need to + :py:meth:`NodeVisitor.dispatch_departure()`) So we need to manually call this. ''' if ignored_options is None: @@ -316,7 +316,7 @@ class CommandCheckVisitor(docutils.nodes.SparseNodeVisitor): While the documentation talks about a 'SparseNodeVisitor.depart_document()' function, this function does not exists. (For details see implementation of - :py:method:`NodeVisitor.dispatch_departure()`) So we need to + :py:meth:`NodeVisitor.dispatch_departure()`) So we need to manually call this. ''' if self.sub_commands: diff --git a/qubes/tests/__init__.py b/qubes/tests/__init__.py index b4c2ec51..809b9879 100644 --- a/qubes/tests/__init__.py +++ b/qubes/tests/__init__.py @@ -172,7 +172,7 @@ def expectedFailureIfTemplate(templates): Decorator for marking specific test as expected to fail only for some templates. Template name is compared as substring, so 'whonix' will handle both 'whonix-ws' and 'whonix-gw'. - templates can be either a single string, or an iterable + templates can be either a single string, or an iterable """ def decorator(func): @functools.wraps(func) diff --git a/qubes/tools/__init__.py b/qubes/tools/__init__.py index 5ee69f0b..18df3214 100644 --- a/qubes/tools/__init__.py +++ b/qubes/tools/__init__.py @@ -303,11 +303,13 @@ class QubesArgumentParser(argparse.ArgumentParser): :py:class:`qubes.Qubes` object, just add argument for custom xml file :param bool want_force_root: add ``--force-root`` option :param mixed vmname_nargs: The number of ``VMNAME`` arguments that should be - consumed. Values include: - - N (an integer) consumes N arguments (and produces a list) - - '?' consumes zero or one arguments - - '*' consumes zero or more arguments (and produces a list) - - '+' consumes one or more arguments (and produces a list) + consumed. Values include: + + - N (an integer) consumes N arguments (and produces a list) + - '?' consumes zero or one arguments + - '*' consumes zero or more arguments (and produces a list) + - '+' consumes one or more arguments (and produces a list) + *kwargs* are passed to :py:class:`argparser.ArgumentParser`. Currenty supported options: diff --git a/qubes/vm/qubesvm.py b/qubes/vm/qubesvm.py index 5aca3cd4..85df8790 100644 --- a/qubes/vm/qubesvm.py +++ b/qubes/vm/qubesvm.py @@ -578,8 +578,8 @@ class QubesVM(qubes.vm.mix.net.NetVMMixin, qubes.vm.BaseVM): @property def block_devices(self): - ''' Return all :py:class:`qubes.storage.BlockDevice`s for current domain - for serialization in the libvirt XML template as . + ''' Return all :py:class:`qubes.storage.BlockDevice` for current domain + for serialization in the libvirt XML template as . ''' for v in self.volumes.values(): block_dev = v.block_device() @@ -1029,7 +1029,7 @@ class QubesVM(qubes.vm.mix.net.NetVMMixin, qubes.vm.BaseVM): :param str service: service name :param qubes.vm.qubesvm.QubesVM source: source domain as presented to - this VM + this VM :param str user: username to run service as :param bool filter_esc: filter escape sequences to protect terminal \ emulator @@ -1199,7 +1199,7 @@ class QubesVM(qubes.vm.mix.net.NetVMMixin, qubes.vm.BaseVM): This function take care to run it as appropriate user. :param command: command to run (array for - :py:meth:`subprocess.check_call`) + :py:meth:`subprocess.check_call`) :param kwargs: args for :py:meth:`subprocess.check_call` :return: None ''' # pylint: disable=redefined-builtin