From 0bb35193b4500e34519a36832e6153384b775bd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Sat, 8 Dec 2018 23:53:55 +0100 Subject: [PATCH] doc: fix rst syntax in documentation, including docstrings --- doc/index.rst | 3 +++ doc/manpages/qvm-volume.rst | 6 +++--- qubesadmin/app.py | 20 +++++++++++--------- qubesadmin/backup/core2.py | 2 +- qubesadmin/backup/restore.py | 6 +++--- qubesadmin/devices.py | 4 ++-- qubesadmin/events/__init__.py | 4 ++-- qubesadmin/storage.py | 2 +- qubesadmin/tools/__init__.py | 13 +++++++------ qubesadmin/tools/dochelpers.py | 4 ++-- qubesadmin/tools/qvm_device.py | 8 ++++---- qubesadmin/tools/qvm_start_gui.py | 6 +++--- 12 files changed, 42 insertions(+), 36 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 78001b0..3680ec7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,6 +11,9 @@ Contents: .. toctree:: :maxdepth: 2 + modules + manpages/index + Indices and tables diff --git a/doc/manpages/qvm-volume.rst b/doc/manpages/qvm-volume.rst index 27f1179..e893fcb 100644 --- a/doc/manpages/qvm-volume.rst +++ b/doc/manpages/qvm-volume.rst @@ -78,9 +78,9 @@ Set property of given volume. Properties currently possible to change: - `rw` - `True` if volume should be writeable by the qube, `False` otherwise - `revisions_to_keep` - how many revisions (previous versions of volume) - should be keep. At each qube shutdown its previous state is saved in new - revision, and the oldest revisions are remove so that only - `revisions_to_keep` are left. Set to `0` to not leave any previous versions. + should be keep. At each qube shutdown its previous state is saved in new + revision, and the oldest revisions are remove so that only + `revisions_to_keep` are left. Set to `0` to not leave any previous versions. aliases: c, set, s diff --git a/qubesadmin/app.py b/qubesadmin/app.py index bf3ec06..0f7e037 100644 --- a/qubesadmin/app.py +++ b/qubesadmin/app.py @@ -193,9 +193,9 @@ class QubesBase(qubesadmin.base.PropertyHolder): :param name: name of storage pool to create :param driver: driver to use, see :py:meth:`pool_drivers` for - available drivers + available drivers :param kwargs: configuration parameters for storage pool, - see :py:meth:`pool_driver_parameters` for a list + see :py:meth:`pool_driver_parameters` for a list ''' # sort parameters only to ease testing, not required by API payload = 'name={}\n'.format(name) + \ @@ -256,9 +256,10 @@ class QubesBase(qubesadmin.base.PropertyHolder): :param str name: name of VM :param str label: label color for new VM :param str template: template to use (if apply for given VM class), - can be also VM object; use None for default value + can be also VM object; use None for default value :param str pool: storage pool to use instead of default one :param dict pools: storage pool for specific volumes + :return new VM object ''' @@ -304,13 +305,14 @@ class QubesBase(qubesadmin.base.PropertyHolder): :param QubesVM or str src_vm: source VM :param str new_name: name of new VM :param str new_cls: name of VM class (`AppVM`, `TemplateVM` etc) - use - None to copy it from *src_vm* + None to copy it from *src_vm* :param str pool: storage pool to use instead of default one :param dict pools: storage pool for specific volumes :param bool ignore_errors: should errors on meta-data setting be only - logged, or abort the whole operation? + logged, or abort the whole operation? :param list ignore_volumes: do not clone volumes on this list, - like 'private' or 'root' + like 'private' or 'root' + :return new VM object ''' @@ -474,7 +476,7 @@ class QubesBase(qubesadmin.base.PropertyHolder): *kwargs* are passed verbatim to :py:meth:`subprocess.Popen`. :param str dest: Destination - may be a VM name or empty - string for default (for a given service) + string for default (for a given service) :param str service: service name :param bool filter_esc: filter escape sequences to protect terminal \ emulator @@ -560,7 +562,7 @@ class QubesLocal(QubesBase): '''Run qrexec service in a given destination :param str dest: Destination - may be a VM name or empty - string for default (for a given service) + string for default (for a given service) :param str service: service name :param bool filter_esc: filter escape sequences to protect terminal \ emulator @@ -650,7 +652,7 @@ class QubesRemote(QubesBase): '''Run qrexec service in a given destination :param str dest: Destination - may be a VM name or empty - string for default (for a given service) + string for default (for a given service) :param str service: service name :param bool filter_esc: filter escape sequences to protect terminal \ emulator diff --git a/qubesadmin/backup/core2.py b/qubesadmin/backup/core2.py index 0fcc330..251154d 100644 --- a/qubesadmin/backup/core2.py +++ b/qubesadmin/backup/core2.py @@ -51,7 +51,7 @@ class Core2VM(qubesadmin.backup.BackupVM): :param node: XML node for the rule :param action: action to apply (in old format it wasn't part of the - rule itself) + rule itself) ''' netmask = node.get('netmask') if netmask is None: diff --git a/qubesadmin/backup/restore.py b/qubesadmin/backup/restore.py index 1a2caa1..3963c58 100644 --- a/qubesadmin/backup/restore.py +++ b/qubesadmin/backup/restore.py @@ -406,7 +406,7 @@ class ExtractWorker3(Process): ''' Relocate files in given director when it's already extracted :param dirname: directory path to handle (relative to backup root), - without trailing slash + without trailing slash ''' for fname, (data_func, size_func) in self.handlers.items(): if not fname.startswith(dirname + '/'): @@ -425,7 +425,7 @@ class ExtractWorker3(Process): '''Cleanup running :py:attr:`tar2_process` :param wait: wait for it termination, otherwise method exit early if - process is still running + process is still running :param terminate: terminate the process if still running ''' if self.tar2_process is None: @@ -721,7 +721,7 @@ def get_supported_hmac_algo(hmac_algorithm=None): '''Generate a list of supported hmac algorithms :param hmac_algorithm: default algorithm, if given, it is placed as a - first element + first element ''' # Start with provided default if hmac_algorithm: diff --git a/qubesadmin/devices.py b/qubesadmin/devices.py index 037c8c8..7b91557 100644 --- a/qubesadmin/devices.py +++ b/qubesadmin/devices.py @@ -162,7 +162,7 @@ class DeviceCollection(object): '''Detach (remove) device from domain. :param DeviceAssignment device_assignment: device to detach - (obtained from :py:meth:`assignments`) + (obtained from :py:meth:`assignments`) ''' if not device_assignment.frontend_domain: device_assignment.frontend_domain = self._vm @@ -188,7 +188,7 @@ class DeviceCollection(object): but be temporarily detached. :param bool persistent: only include devices which are or are not - attached persistently. + attached persistently. ''' assignments_str = self._vm.qubesd_call(None, diff --git a/qubesadmin/events/__init__.py b/qubesadmin/events/__init__.py index 375f31d..30a6e73 100644 --- a/qubesadmin/events/__init__.py +++ b/qubesadmin/events/__init__.py @@ -116,9 +116,9 @@ class EventsDispatcher(object): This is coroutine. :param vm: Listen for events only for this VM, use None to listen for - events about all VMs and not related to any particular VM. + events about all VMs and not related to any particular VM. :param reconnect: should reconnect to qubesd if connection is - interrupted? + interrupted? :rtype: None ''' while True: diff --git a/qubesadmin/storage.py b/qubesadmin/storage.py index c4681f5..a57ad85 100644 --- a/qubesadmin/storage.py +++ b/qubesadmin/storage.py @@ -184,7 +184,7 @@ class Volume(object): self._info = None def is_outdated(self): - ''' Returns `True` if this snapshot of a source volume (for + '''Returns `True` if this snapshot of a source volume (for `snap_on_start`=True) is outdated. ''' self._fetch_info(True) diff --git a/qubesadmin/tools/__init__.py b/qubesadmin/tools/__init__.py index 1f387d2..25b9638 100644 --- a/qubesadmin/tools/__init__.py +++ b/qubesadmin/tools/__init__.py @@ -326,11 +326,12 @@ class QubesArgumentParser(argparse.ArgumentParser): :param bool want_app_no_instance: don't actually instantiate \ :py:class:`qubes.Qubes` object, just add argument for custom xml file :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: @@ -443,7 +444,7 @@ class QubesArgumentParser(argparse.ArgumentParser): class SubParsersHelpAction(argparse._HelpAction): - ''' Print help for all options _and all subparsers_ ''' + ''' Print help for all options and all subparsers ''' # source https://stackoverflow.com/a/24122778 # pylint: disable=protected-access,too-few-public-methods diff --git a/qubesadmin/tools/dochelpers.py b/qubesadmin/tools/dochelpers.py index 37b19c6..6b0f949 100644 --- a/qubesadmin/tools/dochelpers.py +++ b/qubesadmin/tools/dochelpers.py @@ -138,7 +138,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: @@ -205,7 +205,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/qubesadmin/tools/qvm_device.py b/qubesadmin/tools/qvm_device.py index d399514..2b5bdd0 100644 --- a/qubesadmin/tools/qvm_device.py +++ b/qubesadmin/tools/qvm_device.py @@ -37,12 +37,12 @@ def prepare_table(dev_list): ''' Converts a list of :py:class:`qubes.devices.DeviceInfo` objects to a list of tupples for the :py:func:`qubes.tools.print_table`. - If :program:`qvm-devices` is running in a TTY, it will ommit duplicate - data. + If :program:`qvm-devices` is running in a TTY, it will ommit duplicate + data. - :param iterable dev_list: List of :py:class:`qubes.devices.DeviceInfo` + :param iterable dev_list: List of :py:class:`qubes.devices.DeviceInfo` objects. - :returns: list of tupples + :returns: list of tupples ''' output = [] header = [] diff --git a/qubesadmin/tools/qvm_start_gui.py b/qubesadmin/tools/qvm_start_gui.py index d5e8486..3ea57b5 100644 --- a/qubesadmin/tools/qvm_start_gui.py +++ b/qubesadmin/tools/qvm_start_gui.py @@ -186,7 +186,7 @@ class GUILauncher(object): :param vm: VM for which start GUI daemon :param monitor_layout: monitor layout to send; if None, fetch it from - local X server. + local X server. ''' guid_cmd = self.common_guid_args(vm) guid_cmd.extend(['-d', str(vm.xid)]) @@ -243,7 +243,7 @@ class GUILauncher(object): :param vm: VM for which GUI daemon should be started :param force_stubdom: Force GUI daemon for stubdomain, even if the - one for target AppVM is running. + one for target AppVM is running. ''' if vm.virt_mode == 'hvm': yield from self.start_gui_for_stubdomain(vm, @@ -263,7 +263,7 @@ class GUILauncher(object): :param vm: VM to which send monitor layout :param layout: monitor layout to send; if None, fetch it from - local X server. + local X server. :param startup: :return: None '''