From e7f717ec3dfe83293ed134f3d9afc8b6b03217d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Tue, 27 Jun 2017 02:49:13 +0200
Subject: [PATCH] doc: fix formating of policy-related documentation

Fix Sphinx warnings and errors in both doc/ and docstrings.
---
 doc/qubes-policy.rst    |  7 +++++--
 qubespolicy/__init__.py | 24 ++++++++++++------------
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/doc/qubes-policy.rst b/doc/qubes-policy.rst
index 1d400385..1c74545c 100644
--- a/doc/qubes-policy.rst
+++ b/doc/qubes-policy.rst
@@ -11,13 +11,14 @@ Policy consists of a file, which is parsed line-by-line. First matching line
 is used as an action.
 
 Each line consist of three values separated by white characters (space(s), tab(s)):
+
 1. Source specification, which is one of:
 
   - domain name
   - `$anyvm` - any domain
   - `$tag:some-tag` - VM having tag `some-tag`
   - `$type:vm-type` - VM of `vm-type` type, available types:
-      AppVM, TemplateVM, StandaloneVM, DispVM
+    AppVM, TemplateVM, StandaloneVM, DispVM
 
 2. Target specification, one of:
 
@@ -25,7 +26,7 @@ Each line consist of three values separated by white characters (space(s), tab(s
   - `$anyvm` - any domain, excluding dom0
   - `$tag:some-tag` - domain having tag `some-tag`
   - `$type:vm-type` - domain of `vm-type` type, available types:
-      AppVM, TemplateVM, StandaloneVM, DispVM
+    AppVM, TemplateVM, StandaloneVM, DispVM
   - `$default` - used when caller did not specified any VM
   - `$dispvm:vm-name` - _new_ Disposable VM created from AppVM `vm-name`
   - `$dispvm` - _new_ Disposable VM created from AppVM pointed by caller
@@ -38,6 +39,7 @@ Each line consist of three values separated by white characters (space(s), tab(s
 3. Action and optional action parameters, one of:
 
   - `allow` - allow the call, without further questions; optional parameters:
+
     - `target=` - override caller provided call target -
       possible values are: domain name, `$dispvm` or `$dispvm:vm-name`
     - `user=` - call the service using this user, instead of the user
@@ -45,6 +47,7 @@ Each line consist of three values separated by white characters (space(s), tab(s
   - `deny` - deny the call, without further questions; no optional
     parameters are supported
   - `ask` - ask the user for confirmation; optional parameters:
+
     - `target=` - override user provided call target
     - `user=` - call the service using this user, instead of the user
       pointed by target VM's `default_user` property
diff --git a/qubespolicy/__init__.py b/qubespolicy/__init__.py
index 74c54302..b44fd434 100755
--- a/qubespolicy/__init__.py
+++ b/qubespolicy/__init__.py
@@ -84,7 +84,7 @@ def verify_special_value(value, for_target=True):
 
     :param value: value to verify
     :param for_target: should classify target-only values as valid (
-    '$default', '$dispvm')
+        '$default', '$dispvm')
     :return: True or False
     '''
     # pylint: disable=too-many-return-statements
@@ -202,7 +202,7 @@ class PolicyRule(object):
 
         :param system_info: information about the system
         :param policy_value: value from qrexec policy (either self.source or
-        self.target)
+            self.target)
         :param value: value to be compared (source or target)
         :return: True or False
         '''
@@ -265,8 +265,8 @@ class PolicyRule(object):
         Check if given (source, target) matches this policy line.
 
         :param system_info: information about the system - available VMs,
-        their types, labels, tags etc. as returned by
-        :py:func:`app_to_system_info`
+            their types, labels, tags etc. as returned by
+            :py:func:`app_to_system_info`
         :param source: name of the source VM
         :param target: name of the target VM, or None if not specified
         :return: True or False
@@ -392,8 +392,8 @@ class PolicyAction(object):
     def execute(self, caller_ident):
         ''' Execute allowed service call
 
-        :param caller_ident: Service caller ident (`process_ident,source_name,
-        source_id`)
+        :param caller_ident: Service caller ident
+            (`process_ident,source_name, source_id`)
         '''
         assert self.action == Action.allow
         assert self.target is not None
@@ -473,7 +473,7 @@ class Policy(object):
     >>> policy = Policy('some-service')
     >>> action = policy.evaluate(system_info, 'source-name', 'target-name')
     >>> if action.action == Action.ask:
-            (... ask the user, see action.targets_for_ask ...)
+    >>>     # ... ask the user, see action.targets_for_ask ...
     >>>     action.handle_user_response(response, target_chosen_by_user)
     >>> action.execute('process-ident')
 
@@ -668,11 +668,11 @@ def get_system_info():
     data is nested dict structure with this structure:
 
     - domains:
-      - <domain name>:
-        - tags: list of tags
-        - type: domain type
-        - dispvm_allowed: should DispVM based on this VM be allowed
-        - default_dispvm: name of default AppVM for DispVMs started from here
+       - `<domain name>`:
+          - tags: list of tags
+          - type: domain type
+          - dispvm_allowed: should DispVM based on this VM be allowed
+          - default_dispvm: name of default AppVM for DispVMs started from here
 
     '''