docs: Add exception documentation

Provide a list of available exceptions and stress that callers must
handle these themselves.

Change-Id: If3f56524a4642e0e147305758a8c5a4cc88c94bd
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

doc/source/user/exceptions.rst

@@ -0,0 +1,15 @@
+Exceptions
+==========
+
+openstacksdk provides a number of `exceptions`__ for commonly encountered
+issues, such as missing API endpoints, various HTTP error codes, timeouts and
+so forth. It is the responsibility of the calling application to handle these
+exceptions appropriately.
+
+Available exceptions
+--------------------
+
+.. automodule:: openstack.exceptions
+   :members:
+
+.. __: https://docs.python.org/3/library/exceptions.html

doc/source/user/index.rst

@@ -171,6 +171,19 @@ can be customized.
    resource
    service_description
    utils
+
+Errors and warnings
+~~~~~~~~~~~~~~~~~~~
+
+The SDK attempts to provide detailed errors and warnings for things like failed
+requests, deprecated APIs, and invalid configurations. Application developers
+are responsible for handling these errors and can opt into warnings to ensure
+their applications stay up-to-date.
+
+.. toctree::
+   :maxdepth: 1
+
+   exceptions
    warnings
 
 Presentations

openstack/exceptions.py

@@ -57,6 +57,8 @@ class InvalidRequest(SDKException):
 
 
 class HttpException(SDKException, _rex.HTTPError):
+    """The base exception for all HTTP error responses."""
+
     def __init__(
         self,
         message='Error',
@@ -119,26 +121,18 @@ class HttpException(SDKException, _rex.HTTPError):
 class BadRequestException(HttpException):
     """HTTP 400 Bad Request."""
 
-    pass
-
 
 class ForbiddenException(HttpException):
     """HTTP 403 Forbidden Request."""
 
-    pass
-
 
 class ConflictException(HttpException):
     """HTTP 409 Conflict."""
 
-    pass
-
 
 class PreconditionFailedException(HttpException):
     """HTTP 412 Precondition Failed."""
 
-    pass
-
 
 class MethodNotSupported(SDKException):
     """The resource does not support this operation type."""
@@ -161,13 +155,9 @@ class MethodNotSupported(SDKException):
 class DuplicateResource(SDKException):
     """More than one resource exists with that name."""
 
-    pass
-
 
 class ResourceNotFound(HttpException):
-    """No resource exists with that name or id."""
+    """No resource exists with that name or ID."""
-
-    pass
 
 
 NotFoundException = ResourceNotFound
@@ -176,20 +166,14 @@ NotFoundException = ResourceNotFound
 class ResourceTimeout(SDKException):
     """Timeout waiting for resource."""
 
-    pass
-
 
 class ResourceFailure(SDKException):
     """General resource failure."""
 
-    pass
-
 
 class InvalidResourceQuery(SDKException):
     """Invalid query params for resource."""
 
-    pass
-
 
 def _extract_message(obj):
     if isinstance(obj, dict):