Documentation for exceptions

Adds documentation for promenade exceptions.

Change-Id: I26f817f7294df686eeb6f29099dfe69e0b64bbea

docs/source/conf.py

@@ -20,7 +20,6 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

docs/source/exceptions.rst

@@ -0,0 +1,41 @@
+..
+      Copyright 2017 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+Promenade Exceptions
+====================
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ApiError
+    - .. autoexception:: promenade.exceptions.ApiError
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidFormatError
+    - .. autoexception:: promenade.exceptions.InvalidFormatError
+        :members:
+        :show-inheritance:
+        :undoc-members:
+  * - ValidationException
+    - .. autoexception:: promenade.exceptions.ValidationException
+        :members:
+        :show-inheritance:
+        :undoc-members:

docs/source/index.rst

@@ -35,3 +35,4 @@ Promenade Configuration Guide
    configuration/index
    troubleshooting/index
    api
+   exceptions

promenade/exceptions.py

@@ -153,6 +153,10 @@ class PromenadeException(Exception):
     """
     Base error containing enough information to make a promenade-formatted
     error
+
+    **Message:** *Auth is not being handled by any policy engine*.
+
+    **Troubleshoot:**
     """
     EXIT_CODE = 1
 
@@ -221,6 +225,18 @@ class PromenadeException(Exception):
 class ApiError(PromenadeException):
     """
     An error to handle general api errors.
+
+    **Message:** *Expectation Failed*.
+
+    **Troubleshoot:**
+
+    **Message:** *Forbidden*.
+
+    **Troubleshoot:**
+
+    **Message:** *Unauthenticated*.
+
+    **Troubleshoot:**
     """
 
     title = 'Api Error'
@@ -229,7 +245,17 @@ class ApiError(PromenadeException):
 
 class InvalidFormatError(PromenadeException):
     """
-    An exception to cover invalid input formatting
+    An exception to cover invalid input formatting.
+
+    **Message:** *<req.path>: Invalid JSON in body: <various>*.
+
+    **Troubleshoot:** *Make sure the path is correct and the body is valid
+    JSON*.
+
+    **Message:** *<req.path>: Bad input, no body provided*.
+
+    **Troubleshoot:** *Make sure the path is correct and the a body is
+    provided*.
     """
 
     title = 'Invalid Input Error'
@@ -237,6 +263,15 @@ class InvalidFormatError(PromenadeException):
 
 
 class ValidationException(PromenadeException):
+    """
+    **Message:** *"schema" is a required document key*.
+
+    **Troubleshoot:**
+
+    **Message:** *Only kind or schema may be specified, not both*.
+
+    **Troubleshoot:**
+    """
     title = 'Validation Error'
     status = falcon.HTTP_400
 

tox.ini

@@ -22,6 +22,8 @@ whitelist_externals = rm
 deps =
     sphinx>=1.6.2
     sphinx_rtd_theme==0.2.4
+    -r{toxinidir}/requirements-frozen.txt
+    -r{toxinidir}/test-requirements.txt
 commands =
     rm -rf docs/build
     python setup.py build_sphinx {posargs}