doc: fix rst syntax in documentation, including docstrings

doc/index.rst

@@ -11,6 +11,9 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   modules
+   manpages/index
+
 
 
 Indices and tables

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
+    should be keep. At each qube shutdown its previous state is saved in new
-   revision, and the oldest revisions are remove so that only
+    revision, and the oldest revisions are remove so that only
-   `revisions_to_keep` are left. Set to `0` to not leave any previous versions.
+    `revisions_to_keep` are left. Set to `0` to not leave any previous versions.
 
 aliases: c, set, s
 

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

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:

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:

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,

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:

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)

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:
+        consumed. Values include:
-                - N (an integer) consumes N arguments (and produces a list)
+        * N (an integer) consumes N arguments (and produces a list)
-                - '?' consumes zero or one arguments
+        * '?' consumes zero or one arguments
-                - '*' consumes zero or more arguments (and produces a list)
+        * '*' consumes zero or more arguments (and produces a list)
-                - '+' consumes one 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
 

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:

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
+    If :program:`qvm-devices` is running in a TTY, it will ommit duplicate
-        data.
+    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 = []

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
         '''