doc: fix formating of policy-related documentation

Fix Sphinx warnings and errors in both doc/ and docstrings.

doc/qubes-policy.rst

@@ -11,6 +11,7 @@ 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
@@ -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

qubespolicy/__init__.py

@@ -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,7 +668,7 @@ def get_system_info():
     data is nested dict structure with this structure:
 
     - domains:
-      - <domain name>:
+       - `<domain name>`:
           - tags: list of tags
           - type: domain type
           - dispvm_allowed: should DispVM based on this VM be allowed