Armada, Base, & Chartbuilder Armada Exception Documentation

ARMADA-239: Documentation for validation error codes for Armada

2 of 3 commits (Inital Setup and Remaining Exceptions are in seperate commits)

-guide-exceptions.rst contains the files to include in the documentation.
-docs/.../exceptions files contains the format and content of the documenation.
-armada/exceptions files were modified in their comments in order to utilize the
 sphinx-directed method.
-conf.py was modified to indicate the full path for the autoexpection to work
 when merged.

Please Note: If the exception is not raised anywhere, it is not included in the
             documentation.

Change-Id: I6ddd598bfbb26cdd6ff33682844b0739c440d662

armada/exceptions/armada_exceptions.py

@@ -22,6 +22,11 @@ class ArmadaException(base_exception.ArmadaBaseException):
 
 
 class KnownReleasesException(ArmadaException):
-    '''Exception that occurs when no known releases are found'''
+    '''
+    Exception that occurs when no known releases are found.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'No known releases found'

armada/exceptions/base_exception.py

@@ -37,6 +37,8 @@ class ArmadaBaseException(Exception):
 
 
 class ArmadaAPIException(falcon.HTTPError):
+    '''Base class for Armada API Exceptions.'''
+
     status = falcon.HTTP_500
     message = "unknown error"
     title = "Internal Server Error"
@@ -49,6 +51,13 @@ class ArmadaAPIException(falcon.HTTPError):
 
 
 class ActionForbidden(ArmadaAPIException):
+    '''
+    Exception thrown when an action is forbidden.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
+
     status = falcon.HTTP_403
     message = _("Insufficient privilege to perform action.")
     title = _("Action Forbidden")

armada/exceptions/chartbuilder_exceptions.py

@@ -22,7 +22,12 @@ class ChartBuilderException(base_exception.ArmadaBaseException):
 
 
 class DependencyException(ChartBuilderException):
-    '''Exception that occurs when dependencies cannot be resolved.'''
+    '''
+    Exception that occurs when dependencies cannot be resolved.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, chart_name):
         self._chart_name = chart_name
@@ -33,7 +38,12 @@ class DependencyException(ChartBuilderException):
 
 
 class HelmChartBuildException(ChartBuilderException):
-    '''Exception that occurs when Helm Chart fails to build.'''
+    '''
+    Exception that occurs when Helm Chart fails to build.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, chart_name):
         self._chart_name = chart_name
@@ -44,14 +54,25 @@ class HelmChartBuildException(ChartBuilderException):
 
 
 class IgnoredFilesLoadException(ChartBuilderException):
-    '''Exception that occurs when there is an error loading ignored files.'''
+    '''
+    Exception that occurs when there is an error loading files contained in
+    .helmignore.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'An error occurred while loading the ignored files in \
               .helmignore'
 
 
 class MetadataLoadException(ChartBuilderException):
-    ''' Exception that occurs when metadata loading fails.'''
+    '''
+    Exception that occurs when metadata loading fails.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'Failed to load metadata from chart yaml file'
 

docs/source/conf.py

@@ -16,9 +16,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
 
 
 # -- General configuration ------------------------------------------------

docs/source/operations/exceptions/armada-exceptions.inc

@@ -0,0 +1,27 @@
+..
+  Copyright 2018 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.
+
+.. list-table:: **Armada Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - KnownReleasesException
+    - .. autoexception:: armada.exceptions.armada_exceptions.KnownReleasesException
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/operations/exceptions/base-exceptions.inc

@@ -0,0 +1,27 @@
+..
+  Copyright 2018 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.
+
+.. list-table:: **Base Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ActionForbidden
+    - .. autoexception:: armada.exceptions.base_exception.ActionForbidden
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/operations/exceptions/chartbuilder-exceptions.inc

@@ -0,0 +1,42 @@
+..
+  Copyright 2018 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.
+
+.. list-table:: **Chartbuilder Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - DependencyException
+    - .. autoexception:: armada.exceptions.chartbuilder_exceptions.DependencyException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - HelmChartBuildException
+    - .. autoexception:: armada.exceptions.chartbuilder_exceptions.HelmChartBuildException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - IgnoredFilesLoadException
+    - .. autoexception:: armada.exceptions.chartbuilder_exceptions.IgnoredFilesLoadException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - MetadataLoadException
+    - .. autoexception:: armada.exceptions.chartbuilder_exceptions.MetadataLoadException
+         :members:
+         :show-inheritance:
+         :undoc-members:

docs/source/operations/exceptions/guide-exceptions.rst

@@ -18,3 +18,6 @@ Armada Exceptions
 =================
 
 .. include:: api-exceptions.inc
+.. include:: armada-exceptions.inc
+.. include:: base-exceptions.inc
+.. include:: chartbuilder-exceptions.inc