Cleanup docstrings

Some docstrings were not valid RST, which led to incorrect display
and warnings and errors when building the docs.

Change-Id: I66d823a2a5a2a05d51ba1a37a2c22ded2c09f748

keystone/common/authorization.py

@@ -30,11 +30,12 @@ AUTH_CONTEXT_ENV = 'KEYSTONE_AUTH_CONTEXT'
 Auth context is essentially the user credential used for policy enforcement.
 It is a dictionary with the following attributes:
 
-user_id: user ID of the principal
+* ``user_id``: user ID of the principal
-project_id (optional): project ID of the scoped project if auth is
+* ``project_id`` (optional): project ID of the scoped project if auth is
-                       project-scoped
+                             project-scoped
-domain_id (optional): domain ID of the scoped domain if auth is domain-scoped
+* ``domain_id`` (optional): domain ID of the scoped domain if auth is
-roles (optional): list of role names for the given scope
+                            domain-scoped
+* ``roles`` (optional): list of role names for the given scope
 
 """
 

keystone/common/driver_hints.py

@@ -43,12 +43,13 @@ class Hints(list):
 
         Each filter term consists of:
 
-        name: the name of the attribute being matched
+        * ``name``: the name of the attribute being matched
-        value: the value against which it is being matched
+        * ``value``: the value against which it is being matched
-        comparator: the operation, which can be one of 'equals',
+        * ``comparator``: the operation, which can be one of ``equals``,
-                    'startswith' or 'endswith'
+                          ``startswith`` or ``endswith``
-        case_sensitive: whether any comparison should take account of case
+        * ``case_sensitive``: whether any comparison should take account of
-        type: will always be 'filter'
+                              case
+        * ``type``: will always be 'filter'
 
         """
         return [x for x in self if x['type'] == 'filter']

keystone/contrib/federation/controllers.py

@@ -30,10 +30,12 @@ class _ControllerBase(controller.V3Controller):
     """Base behaviors for federation controllers.
 
     Two new class parameters:
-    - _mutable_parameters - set of parameters that can be changed by users.
+
-                            Usually used by cls.check_immutable_params()
+    * `_mutable_parameters` - set of parameters that can be changed by users.
-    - _public_parameters - set of parameters that are exposed to the user.
+                              Usually used by cls.check_immutable_params()
-                           Usually used by cls.filter_params()
+    * `_public_parameters` - set of parameters that are exposed to the user.
+                             Usually used by cls.filter_params()
+
     """
 
     @classmethod
@@ -46,7 +48,7 @@ class _ControllerBase(controller.V3Controller):
 
         :param ref: a dictionary representing deserialized request to be
                     stored
-        :raises exception.ImmutableAttributeError
+        :raises: :class:`keystone.exception.ImmutableAttributeError`
 
         """
         ref_keys = set(ref.keys())

keystone/tests/test_v3_filters.py

@@ -109,6 +109,7 @@ class IdentityTestFilteredCase(filtering.FilterTests,
         """GET /users?domain_id=mydomain (filtered)
 
         Test Plan:
+
         - Update policy so api is unprotected
         - Use an un-scoped token to make sure we can filter the
           users by domainB, getting back the 2 users in that domain
@@ -126,6 +127,7 @@ class IdentityTestFilteredCase(filtering.FilterTests,
         """GET /domains?enabled=0
 
         Test Plan:
+
         - Update policy for no protection on api
         - Filter by the 'enabled' boolean to get disabled domains, which
           should return just domainC
@@ -168,6 +170,7 @@ class IdentityTestFilteredCase(filtering.FilterTests,
         """GET /domains?enabled&name=myname
 
         Test Plan:
+
         - Update policy for no protection on api
         - Filter by the 'enabled' boolean and name - this should
           return a single domain
@@ -186,6 +189,7 @@ class IdentityTestFilteredCase(filtering.FilterTests,
         """GET /users?name=%myname%
 
         Test Plan:
+
         - Update policy so api is unprotected
         - Update a user with name that has filter escape characters
         - Ensure we can filter on it
@@ -269,6 +273,7 @@ class IdentityTestFilteredCase(filtering.FilterTests,
         """GET /users?name=<injected sql_statement>
 
         Test Plan:
+
         - Attempt to get all entities back by passing a two-term attribute
         - Attempt to piggyback filter to damage DB (e.g. drop table)
 

keystone/tests/test_v3_protection.py

@@ -350,10 +350,10 @@ class IdentityTestv3CloudPolicySample(test_v3.RestfulTestCase):
         - One project, which name is 'project'
         - domainA has three users: domain_admin_user, project_admin_user and
           just_a_user:
+
           - domain_admin_user has role 'admin' on domainA,
           - project_admin_user has role 'admin' on the project,
-          - just_a_user has a non-admin role on both domainA and the
+          - just_a_user has a non-admin role on both domainA and the project.
-            project.
         - admin_domain has user cloud_admin_user, with an 'admin' role
           on admin_domain.