diff --git a/keystone/common/authorization.py b/keystone/common/authorization.py
index 4479cf4b0c..74957e4fde 100644
--- a/keystone/common/authorization.py
+++ b/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
-project_id (optional): project ID of the scoped project if auth is
-                       project-scoped
-domain_id (optional): domain ID of the scoped domain if auth is domain-scoped
-roles (optional): list of role names for the given scope
+* ``user_id``: user ID of the principal
+* ``project_id`` (optional): project ID of the scoped project if auth is
+                             project-scoped
+* ``domain_id`` (optional): domain ID of the scoped domain if auth is
+                            domain-scoped
+* ``roles`` (optional): list of role names for the given scope
 
 """
 
diff --git a/keystone/common/driver_hints.py b/keystone/common/driver_hints.py
index e90f9c9001..9717649301 100644
--- a/keystone/common/driver_hints.py
+++ b/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
-        value: the value against which it is being matched
-        comparator: the operation, which can be one of 'equals',
-                    'startswith' or 'endswith'
-        case_sensitive: whether any comparison should take account of case
-        type: will always be 'filter'
+        * ``name``: the name of the attribute being matched
+        * ``value``: the value against which it is being matched
+        * ``comparator``: the operation, which can be one of ``equals``,
+                          ``startswith`` or ``endswith``
+        * ``case_sensitive``: whether any comparison should take account of
+                              case
+        * ``type``: will always be 'filter'
 
         """
         return [x for x in self if x['type'] == 'filter']
diff --git a/keystone/contrib/federation/controllers.py b/keystone/contrib/federation/controllers.py
index caa17b7be4..83c6758274 100644
--- a/keystone/contrib/federation/controllers.py
+++ b/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()
-    - _public_parameters - set of parameters that are exposed to the user.
-                           Usually used by cls.filter_params()
+
+    * `_mutable_parameters` - set of parameters that can be changed by users.
+                              Usually used by cls.check_immutable_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())
diff --git a/keystone/tests/test_v3_filters.py b/keystone/tests/test_v3_filters.py
index b3d84a8220..216700a56a 100644
--- a/keystone/tests/test_v3_filters.py
+++ b/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)
 
diff --git a/keystone/tests/test_v3_protection.py b/keystone/tests/test_v3_protection.py
index a357daebc8..864cffccfd 100644
--- a/keystone/tests/test_v3_protection.py
+++ b/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
-            project.
+          - just_a_user has a non-admin role on both domainA and the project.
         - admin_domain has user cloud_admin_user, with an 'admin' role
           on admin_domain.