Fix doc build errors

There were some parts that had invalid RST in their docstrings
which caused warnings and errors to be generated.

Related-Bug: #1278662
Change-Id: Ibb53e6f49b5fa100fa6ecfe47331f9a70729d03b

doc/source/index.rst

@@ -16,7 +16,7 @@ Contents:
    using-api-v2
    using-api-v3
 
-   api/autoindex
+   api/modules
 
 Contributing
 ============

keystoneclient/common/cms.py

@@ -171,38 +171,45 @@ def is_ans1_token(token):
 
     thx to ayoung for sorting this out.
 
-    base64 decoded hex representation of MII is 3082
-    In [3]: binascii.hexlify(base64.b64decode('MII='))
-    Out[3]: '3082'
+    base64 decoded hex representation of MII is 3082::
+
+      In [3]: binascii.hexlify(base64.b64decode('MII='))
+      Out[3]: '3082'
 
     re: http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf
 
-    pg4:  For tags from 0 to 30 the first octet is the identfier
-    pg10: Hex 30 means sequence, followed by the length of that sequence.
-    pg5:  Second octet is the length octet
-          first bit indicates short or long form, next 7 bits encode the number
-          of subsequent octets that make up the content length octets as an
-          unsigned binary int
+    ::
 
-          82 = 10000010 (first bit indicates long form)
-          0000010 = 2 octets of content length
-          so read the next 2 octets to get the length of the content.
+      pg4:  For tags from 0 to 30 the first octet is the identfier
+      pg10: Hex 30 means sequence, followed by the length of that sequence.
+      pg5:  Second octet is the length octet
+            first bit indicates short or long form, next 7 bits encode the
+            number of subsequent octets that make up the content length octets
+            as an unsigned binary int
+
+            82 = 10000010 (first bit indicates long form)
+            0000010 = 2 octets of content length
+            so read the next 2 octets to get the length of the content.
 
     In the case of a very large content length there could be a requirement to
     have more than 2 octets to designate the content length, therefore
     requiring us to check for MIM, MIQ, etc.
-    In [4]: base64.b64encode(binascii.a2b_hex('3083'))
-    Out[4]: 'MIM='
-    In [5]: base64.b64encode(binascii.a2b_hex('3084'))
-    Out[5]: 'MIQ='
-    Checking for MI would become invalid at 16 octets of content length
-    10010000 = 90
-    In [6]: base64.b64encode(binascii.a2b_hex('3090'))
-    Out[6]: 'MJA='
-    Checking for just M is insufficient
+
+    ::
+
+      In [4]: base64.b64encode(binascii.a2b_hex('3083'))
+      Out[4]: 'MIM='
+      In [5]: base64.b64encode(binascii.a2b_hex('3084'))
+      Out[5]: 'MIQ='
+      Checking for MI would become invalid at 16 octets of content length
+      10010000 = 90
+      In [6]: base64.b64encode(binascii.a2b_hex('3090'))
+      Out[6]: 'MJA='
+      Checking for just M is insufficient
 
     But we will only check for MII:
-    Max length of the content using 2 octets is 7FFF or 32767
+    Max length of the content using 2 octets is 7FFF or 32767.
+
     It's not practical to support a token of this length or greater in http
     therefore, we will check for MII only and ignore the case of larger tokens
     """

keystoneclient/middleware/auth_token.py

@@ -1180,9 +1180,9 @@ class AuthProtocol(object):
         :param retry: flag that forces the middleware to retry
                       user authentication when an indeterminate
                       response is received. Optional.
-        :return token object received from keystone on success
-        :raise InvalidUserToken if token is rejected
-        :raise ServiceError if unable to authenticate token
+        :return: token object received from keystone on success
+        :raise InvalidUserToken: if token is rejected
+        :raise ServiceError: if unable to authenticate token
 
         """
         # Determine the highest api version we can use.

keystoneclient/service_catalog.py

@@ -154,8 +154,8 @@ class ServiceCatalog(object):
         :param string service_type: Service type of the endpoint.
         :param string endpoint_type: Type of endpoint.
                                      Possible values: public or publicURL,
-                                         internal or internalURL,
-                                         admin or adminURL
+                                     internal or internalURL, admin or
+                                     adminURL
         :param string region_name: Region of the endpoint.
 
         :returns: tuple of urls or None (if no match found)

keystoneclient/tests/test_auth_token_middleware.py

@@ -1644,7 +1644,7 @@ class TokenExpirationTest(BaseAuthTokenMiddlewareTest):
         """Ensure we cannot retrieve a token from the cache.
 
         Getting a token from the cache should return None when the token data
-        in the cache stores the expires time as a *nix style timestamp.
+        in the cache stores the expires time as a \*nix style timestamp.
 
         """
         token = 'mytoken'

keystoneclient/v2_0/client.py

@@ -57,7 +57,7 @@ class Client(httpclient.HTTPClient):
     :param string key: Path to the Privacy Enhanced Mail (PEM) file which
                        contains the unencrypted client private key needed
                        to established two-way SSL connection with the
-                      identity service. (optional)
+                       identity service. (optional)
     :param string cacert: Path to the Privacy Enhanced Mail (PEM) file which
                           contains the trusted authority X.509 certificates
                           needed to established SSL connection with the
@@ -73,8 +73,8 @@ class Client(httpclient.HTTPClient):
 
     .. warning::
 
-    If debug is enabled, it may show passwords in plain text as a part of its
-    output.
+        If debug is enabled, it may show passwords in plain text as a part of
+        its output.
 
 
     The client can be created and used like a user or in a strictly

keystoneclient/v3/users.py

@@ -51,7 +51,7 @@ class UserManager(base.CrudManager):
 
         .. warning::
 
-        The project argument is deprecated, use default_project instead.
+          The project argument is deprecated, use default_project instead.
 
         If both default_project and project is provided, the default_project
         will be used.
@@ -82,7 +82,7 @@ class UserManager(base.CrudManager):
 
         .. warning::
 
-        The project argument is deprecated, use default_project instead.
+          The project argument is deprecated, use default_project instead.
 
         If both default_project and project is provided, the default_project
         will be used.
@@ -113,7 +113,7 @@ class UserManager(base.CrudManager):
 
         .. warning::
 
-        The project argument is deprecated, use default_project instead.
+          The project argument is deprecated, use default_project instead.
 
         If both default_project and project is provided, the default_project
         will be used.

test-requirements.txt

@@ -8,6 +8,7 @@ mock>=1.0
 mox3>=0.7.0
 pycrypto>=2.6
 sphinx>=1.1.2,<1.2
+stevedore>=0.14
 testrepository>=0.0.18
 testresources>=0.2.4
 testtools>=0.9.34