Lint, Manifest, Override, Source, & Tiller Armada Exception Documentation

ARMADA-239: Documentation for validation error codes for Armada

3 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.

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

Change-Id: Ie093cb3252b199bfc7fcd62284501e573d89ed8a

armada/exceptions/lint_exceptions.py

@@ -22,7 +22,12 @@ class LintException(base_exception.ArmadaBaseException):
 
 
 class InvalidManifestException(LintException):
-    '''Exception for invalid manifests.'''
+    '''
+    Exception for invalid manifests.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'Armada manifest invalid.'
 
@@ -46,6 +51,11 @@ class InvalidReleaseException(LintException):
 
 
 class InvalidArmadaObjectException(LintException):
-    '''Exception that occurs when an Armada object is not declared.'''
+    '''
+    Exception that occurs when an Armada object is not declared.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'An Armada object was not declared.'

armada/exceptions/manifest_exceptions.py

@@ -16,4 +16,12 @@ from armada.exceptions import base_exception as base
 
 
 class ManifestException(base.ArmadaBaseException):
+    """
+    An exception occurred while attempting to build an Armada manifest. The
+    exception will return with details as to why.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    """
+
     message = 'An error occurred while generating the manifest: %(details)s.'

armada/exceptions/override_exceptions.py

@@ -38,6 +38,9 @@ class InvalidOverrideTypeException(OverrideException):
 class InvalidOverrideFileException(OverrideException):
     '''
     Exception that occurs when an invalid override file is provided.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, filename):
@@ -49,6 +52,9 @@ class InvalidOverrideFileException(OverrideException):
 class InvalidOverrideValueException(OverrideException):
     '''
     Exception that occurs when an invalid value is used with the set flag.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, override_command):
@@ -61,6 +67,9 @@ class InvalidOverrideValueException(OverrideException):
 class UnknownDocumentOverrideException(OverrideException):
     '''
     Exception that occurs when an invalid value is used with the set flag.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, doc_type, doc_name):

armada/exceptions/source_exceptions.py

@@ -22,7 +22,12 @@ class SourceException(base_exception.ArmadaBaseException):
 
 
 class GitException(SourceException):
-    '''Exception when an error occurs cloning a Git repository.'''
+    '''
+    Exception when an error occurs cloning a Git repository.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, location):
         self._location = location
@@ -81,8 +86,12 @@ class SourceCleanupException(SourceException):
 
 
 class TarballDownloadException(SourceException):
-    '''Exception that occurs when the tarball cannot be downloaded
-        from the provided URL
+    '''
+    Exception that occurs when the tarball cannot be downloaded from the
+    provided URL.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, tarball_url):
@@ -93,7 +102,12 @@ class TarballDownloadException(SourceException):
 
 
 class TarballExtractException(SourceException):
-    '''Exception that occurs when extracting the tarball fails'''
+    '''
+    Exception that occurs when extracting the tarball fails.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, tarball_dir):
         self._tarball_dir = tarball_dir
@@ -103,7 +117,12 @@ class TarballExtractException(SourceException):
 
 
 class InvalidPathException(SourceException):
-    '''Exception that occurs when a nonexistant path is accessed'''
+    '''
+    Exception that occurs when a nonexistant path is accessed.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, path):
         self._path = path
@@ -113,7 +132,12 @@ class InvalidPathException(SourceException):
 
 
 class ChartSourceException(SourceException):
-    '''Exception for unknown chart source type.'''
+    '''
+    Exception for unknown chart source type.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, chart_name, source_type):
         self._chart_name = chart_name

armada/exceptions/tiller_exceptions.py

@@ -22,7 +22,12 @@ class TillerException(ex):
 
 
 class TillerServicesUnavailableException(TillerException):
-    '''Exception for Tiller services unavailable.'''
+    '''
+    Exception for tiller service being unavailable.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'Tiller services unavailable.'
 
@@ -54,7 +59,12 @@ class PostUpdateJobDeleteException(TillerException):
 
 
 class PostUpdateJobCreateException(TillerException):
-    '''Exception that occurs when a job creation fails.'''
+    '''
+    Exception that occurs when a job creation fails.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, name, namespace):
 
@@ -65,7 +75,12 @@ class PostUpdateJobCreateException(TillerException):
 
 
 class PreUpdateJobDeleteException(TillerException):
-    '''Exception that occurs when a job deletion'''
+    '''
+    Exception that occurs when a job deletion.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, name, namespace):
 
@@ -90,6 +105,9 @@ class ReleaseException(TillerException):
     '''
     Exception that occurs when a release fails to install, upgrade, delete,
     or test.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, name, status, action):
@@ -101,13 +119,23 @@ class ReleaseException(TillerException):
 
 
 class ChannelException(TillerException):
-    '''Exception that occurs during a failed gRPC channel creation'''
+    '''
+    Exception that occurs during a failed gRPC channel creation
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'Failed to create gRPC channel.'
 
 
 class GetReleaseStatusException(TillerException):
-    '''Exception that occurs during a failed Release Testing'''
+    '''
+    Exception that occurs during a failed Release Testing.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     def __init__(self, release, version):
         message = 'Failed to get {} status {} version'.format(
@@ -130,6 +158,9 @@ class TillerPodNotFoundException(TillerException):
     '''
     Exception that occurs when a tiller pod cannot be found using the labels
     specified in the Armada config.
+
+    **Troubleshoot:**
+    *Coming Soon*
     '''
 
     def __init__(self, labels):
@@ -139,12 +170,22 @@ class TillerPodNotFoundException(TillerException):
 
 
 class TillerPodNotRunningException(TillerException):
-    '''Exception that occurs when no Tiller pod is found in a running state'''
+    '''
+    Exception that occurs when no tiller pod is found in a running state.
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'No Tiller pods found in running state'
 
 
 class TillerVersionException(TillerException):
-    '''Exception that occurs during a failed Release Testing'''
+    '''
+    Exception that occurs during a failed Release Testing
+
+    **Troubleshoot:**
+    *Coming Soon*
+    '''
 
     message = 'Failed to get Tiller Version'

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

@@ -21,3 +21,8 @@ Armada Exceptions
 .. include:: armada-exceptions.inc
 .. include:: base-exceptions.inc
 .. include:: chartbuilder-exceptions.inc
+.. include:: lint-exceptions.inc
+.. include:: manifest-exceptions.inc
+.. include:: override-exceptions.inc
+.. include:: source-exceptions.inc
+.. include:: tiller-exceptions.inc

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

@@ -0,0 +1,32 @@
+..
+  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.
+
+.. list-table:: **Lint Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - InvalidArmadaObjectException
+    - .. autoexception:: armada.exceptions.lint_exceptions.InvalidArmadaObjectException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidManifestException
+    - .. autoexception:: armada.exceptions.lint_exceptions.InvalidManifestException
+         :members:
+         :show-inheritance:
+         :undoc-members:

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

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

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

@@ -0,0 +1,37 @@
+..
+  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.
+
+.. list-table:: **Override Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - InvalidOverrideFileException
+    - .. autoexception:: armada.exceptions.override_exceptions.InvalidOverrideFileException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidOverrideValueException
+    - .. autoexception:: armada.exceptions.override_exceptions.InvalidOverrideValueException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - UnknownDocumentOverrideException
+    - .. autoexception:: armada.exceptions.override_exceptions.UnknownDocumentOverrideException
+         :members:
+         :show-inheritance:
+         :undoc-members:

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

@@ -0,0 +1,47 @@
+..
+  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.
+
+.. list-table:: **Source Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ChartSourceException
+    - .. autoexception:: armada.exceptions.source_exceptions.ChartSourceException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - GitException
+    - .. autoexception:: armada.exceptions.source_exceptions.GitException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - InvalidPathException
+    - .. autoexception:: armada.exceptions.source_exceptions.InvalidPathException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - TarballDownloadException
+    - .. autoexception:: armada.exceptions.source_exceptions.TarballDownloadException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - TarballExtractException
+    - .. autoexception:: armada.exceptions.source_exceptions.TarballExtractException
+         :members:
+         :show-inheritance:
+         :undoc-members:

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

@@ -0,0 +1,47 @@
+..
+  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.
+
+.. list-table:: **Tiller Exceptions**
+  :widths: 5 50
+  :header-rows: 1
+
+  * - Exception Name
+    - Description
+  * - ChannelException
+    - .. autoexception:: armada.exceptions.tiller_exceptions.ChannelException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - GetReleaseStatusException
+    - .. autoexception:: armada.exceptions.tiller_exceptions.GetReleaseStatusException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - PostUpdateJobCreateException
+    - .. autoexception:: armada.exceptions.tiller_exceptions.PostUpdateJobCreateException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - PreUpdateJobDeleteException
+    - .. autoexception:: armada.exceptions.tiller_exceptions.PreUpdateJobDeleteException
+         :members:
+         :show-inheritance:
+         :undoc-members:
+  * - ReleaseException
+    - .. autoexception:: armada.exceptions.tiller_exceptions.ReleaseException
+         :members:
+         :show-inheritance:
+         :undoc-members: