Cleanup docs - raises class

The argument to the :raises: directive is the class name. If the
class name is a valid reference it's rendered as a link to the
class. This change cleans up the :raises: directives to use the
reference correctly and use a valid class reference.

Change-Id: I84188b60de0ab4c6b5b2fb5a203c43bfde094707

keystoneclient/adapter.py

@@ -93,7 +93,8 @@ class Adapter(object):
                      on the session. (optional)
         :type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
 
-        :raises AuthorizationFailure: if a new token fetch fails.
+        :raises keystoneclient.exceptions.AuthorizationFailure: if a new token
+            fetch fails.
 
         :returns string: A valid token.
         """
@@ -106,7 +107,8 @@ class Adapter(object):
                      the session. (optional)
         :type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
 
-        :raises MissingAuthPlugin: if a plugin is not available.
+        :raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
+                                                             available.
 
         :returns string: An endpoint if available or None.
         """

keystoneclient/auth/base.py

@@ -33,7 +33,8 @@ def get_plugin_class(name):
 
     :returns: An auth plugin class.
 
-    :raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
+    :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
+                                                        created.
     """
     try:
         mgr = stevedore.DriverManager(namespace=PLUGIN_NAMESPACE,

keystoneclient/auth/cli.py

@@ -31,7 +31,8 @@ def register_argparse_arguments(parser, argv, default=None):
 
     :returns: The plugin class that will be loaded or None if not provided.
 
-    :raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
+    :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
+                                                        created.
     """
     in_parser = argparse.ArgumentParser(add_help=False)
     env_plugin = os.environ.get('OS_AUTH_PLUGIN', default)
@@ -68,7 +69,8 @@ def load_from_argparse_arguments(namespace, **kwargs):
 
     :returns: An auth plugin, or None if a name is not provided.
 
-    :raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
+    :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
+                                                        created.
     """
     if not namespace.os_auth_plugin:
         return None

keystoneclient/auth/conf.py

@@ -90,7 +90,8 @@ def load_from_conf_options(conf, group, **kwargs):
 
     :returns plugin: An authentication Plugin or None if a name is not provided
 
-    :raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
+    :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
+                                                        created.
     """
     # NOTE(jamielennox): plugins are allowed to specify a 'section' which is
     # the group that auth options should be taken from. If not present they

keystoneclient/auth/identity/base.py

@@ -73,8 +73,11 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         when invoked. If you are looking to just retrieve the current auth
         data then you should use get_access.
 
-        :raises InvalidResponse: The response returned wasn't appropriate.
+        :raises keystoneclient.exceptions.InvalidResponse: The response
-        :raises HttpError: An error from an invalid HTTP response.
+                                                           returned wasn't
+                                                           appropriate.
+        :raises keystoneclient.exceptions.HttpError: An error from an invalid
+                                                     HTTP response.
 
         :returns AccessInfo: Token access information.
         """
@@ -84,7 +87,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
 
         If a valid token is not present then a new one will be fetched.
 
-        :raises HttpError: An error from an invalid HTTP response.
+        :raises keystoneclient.exceptions.HttpError: An error from an invalid
+                                                     HTTP response.
 
         :return string: A valid token.
         """
@@ -118,7 +122,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         If a valid AccessInfo is present then it is returned otherwise a new
         one will be fetched.
 
-        :raises HttpError: An error from an invalid HTTP response.
+        :raises keystoneclient.exceptions.HttpError: An error from an invalid
+                                                     HTTP response.
 
         :returns AccessInfo: Valid AccessInfo
         """
@@ -169,7 +174,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         :param tuple version: The minimum version number required for this
                               endpoint. (optional)
 
-        :raises HttpError: An error from an invalid HTTP response.
+        :raises keystoneclient.exceptions.HttpError: An error from an invalid
+                                                     HTTP response.
 
         :return string or None: A valid endpoint URL or None if not available.
         """
@@ -240,8 +246,10 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
                                    (optional) Defaults to None (use a token
                                    if a plugin is installed).
 
-        :raises: DiscoveryFailure if for some reason the lookup fails.
+        :raises keystoneclient.exceptions.DiscoveryFailure: if for some reason
-        :raises: HttpError An error from an invalid HTTP response.
+                                                            the lookup fails.
+        :raises keystoneclient.exceptions.HttpError: An error from an invalid
+                                                     HTTP response.
 
         :returns: A discovery object with the results of looking up that URL.
         """

keystoneclient/client.py

@@ -36,8 +36,10 @@ def Client(version=None, unstable=False, session=None, **kwargs):
     :returns: New keystone client object
               (keystoneclient.v2_0.Client or keystoneclient.v3.Client).
 
-    :raises: DiscoveryFailure if the server's response is invalid
+    :raises keystoneclient.exceptions.DiscoveryFailure: if the server's
-    :raises: VersionNotAvailable if a suitable client cannot be found.
+                                                        response is invalid
+    :raises keystoneclient.exceptions.VersionNotAvailable: if a suitable client
+                                                           cannot be found.
     """
     if not session:
         session = client_session.Session.construct(kwargs)

keystoneclient/common/cms.py

@@ -132,8 +132,10 @@ def cms_verify(formatted, signing_cert_file_name, ca_file_name,
                inform=PKI_ASN1_FORM):
     """Verifies the signature of the contents IAW CMS syntax.
 
-    :raises: subprocess.CalledProcessError
+    :raises subprocess.CalledProcessError:
-    :raises: CertificateConfigError if certificate is not configured properly.
+    :raises keystoneclient.exceptions.CertificateConfigError: if certificate
+                                                              is not configured
+                                                              properly.
     """
     _ensure_subprocess()
     if isinstance(formatted, six.string_types):

keystoneclient/contrib/auth/v3/saml2.py

@@ -519,7 +519,7 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
 
         :param session
         :returns: True if cookie jar is nonempty, False otherwise
-        :raises: AttributeError in case cookies are not find anywhere
+        :raises AttributeError: in case cookies are not find anywhere
 
         """
         try:
@@ -704,11 +704,12 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
         :param session : a session object to send out HTTP requests.
         :type session: keystoneclient.session.Session
 
-        :raises: exceptions.AuthorizationFailure when HTTP response from the
+        :raises keystoneclient.exceptions.AuthorizationFailure: when HTTP
-                 ADFS server is not a valid XML ADFS security token.
+                 response from the ADFS server is not a valid XML ADFS security
-        :raises: exceptions.InternalServerError: If response status code is
+                 token.
-                 HTTP 500 and the response XML cannot be recognized.
+        :raises keystoneclient.exceptions.InternalServerError: If response
-
+                 status code is HTTP 500 and the response XML cannot be
+                 recognized.
 
         """
         def _get_failure(e):
@@ -797,8 +798,8 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
         :param session : a session object to send out HTTP requests.
         :type session: keystoneclient.session.Session
 
-        :raises: exceptions.AuthorizationFailure: in case session object
+        :raises keystoneclient.exceptions.AuthorizationFailure: in case session
-        has empty cookie jar.
+        object has empty cookie jar.
 
         """
         if self._cookies(session) is False:

keystoneclient/discover.py

@@ -261,8 +261,10 @@ class Discover(_discover.Discover):
 
         :returns: An instantiated identity client object.
 
-        :raises: DiscoveryFailure if the server response is invalid
+        :raises keystoneclient.exceptions.DiscoveryFailure: if the server
-        :raises: VersionNotAvailable if a suitable client cannot be found.
+                                                            response is invalid
+        :raises keystoneclient.exceptions.VersionNotAvailable: if a suitable
+            client cannot be found.
         """
         version_data = self._calculate_version(version, unstable)
         return self._create_client(version_data, **kwargs)

keystoneclient/exceptions.py

@@ -14,6 +14,15 @@
 #    under the License.
 """
 Exception definitions.
+
+.. py:exception:: AuthorizationFailure
+
+.. py:exception:: ClientException
+
+.. py:exception:: HttpError
+
+.. py:exception:: Unauthorized
+
 """
 
 #flake8: noqa

keystoneclient/httpclient.py

@@ -364,9 +364,10 @@ class HTTPClient(baseclient.Client, base.BaseAuthPlugin):
         self.management_url from the details provided in the token.
 
         :returns: ``True`` if authentication was successful.
-        :raises: AuthorizationFailure if unable to authenticate or validate
+        :raises keystoneclient.exceptions.AuthorizationFailure: if unable to
-                 the existing authorization token
+            authenticate or validate the existing authorization token
-        :raises: ValueError if insufficient parameters are used.
+        :raises keystoneclient.exceptions.ValueError: if insufficient
+                                                      parameters are used.
 
         If keyring is used, token is retrieved from keyring instead.
         Authentication will only be necessary if any of the following

keystoneclient/session.py

@@ -259,8 +259,8 @@ class Session(object):
                        'allow_redirects' is ignored as redirects are handled
                        by the session.
 
-        :raises exceptions.ClientException: For connection failure, or to
+        :raises keystoneclient.exceptions.ClientException: For connection
-                                            indicate an error response code.
+            failure, or to indicate an error response code.
 
         :returns: The response to the request.
         """
@@ -500,7 +500,8 @@ class Session(object):
                      on the session. (optional)
         :type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
 
-        :raises AuthorizationFailure: if a new token fetch fails.
+        :raises keystoneclient.exceptions.AuthorizationFailure: if a new token
+                                                                fetch fails.
 
         :returns string: A valid token.
         """
@@ -523,7 +524,8 @@ class Session(object):
                      the session. (optional)
         :type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
 
-        :raises MissingAuthPlugin: if a plugin is not available.
+        :raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
+                                                             available.
 
         :returns string: An endpoint if available or None.
         """

keystoneclient/v2_0/client.py

@@ -158,8 +158,8 @@ class Client(httpclient.HTTPClient):
         password.
 
         :returns: access.AccessInfo if authentication was successful.
-        :raises: AuthorizationFailure if unable to authenticate or validate
+        :raises keystoneclient.exceptions.AuthorizationFailure: if unable to
-                 the existing authorization token
+            authenticate or validate the existing authorization token
         """
         try:
             if auth_url is None:

keystoneclient/v3/client.py

@@ -227,9 +227,10 @@ EndpointPolicyManager`
         be used in the request.
 
         :returns: access.AccessInfo if authentication was successful.
-        :raises: AuthorizationFailure if unable to authenticate or validate
+        :raises keystoneclient.exceptions.AuthorizationFailure: if unable to
-                 the existing authorization token
+            authenticate or validate the existing authorization token.
-        :raises: Unauthorized if authentication fails due to invalid token
+        :raises keystoneclient.exceptions.Unauthorized: if authentication fails
+            due to invalid token.
 
         """
         try: