docs: Use sphinx-apidoc library for autodoc compatibility

This package is used for generation autodoc documentation
automatically which can be linked to by Deckhand
documentation from other places. This is to make autodoc
generation work in RTD.

More info: https://pypi.org/project/sphinxcontrib-apidoc/

Change-Id: I43aac82728e5935a5a2626f2fd29d7a7188d19f9

.gitignore

@@ -66,10 +66,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-doc/_build/
-doc/source/_static/
-
 # PyBuilder
 target/
 

deckhand/common/utils.py

@@ -212,11 +212,13 @@ def _execute_data_expansion(data, jsonpath):
 
 def jsonpath_replace(data, value, jsonpath, pattern=None, recurse=None):
     """Update value in ``data`` at the path specified by ``jsonpath``.
+
     If the nested path corresponding to ``jsonpath`` isn't found in ``data``,
     the path is created as an empty ``{}`` for each sub-path along the
     ``jsonpath``.
 
     Example::
+
         doc = {
             'data': {
                 'some_url': http://admin:INSERT_PASSWORD_HERE@svc-name:8080/v1
@@ -248,6 +250,7 @@ def jsonpath_replace(data, value, jsonpath, pattern=None, recurse=None):
     :raises: MissingDocumentPattern if ``pattern`` is not None and
         ``data[jsonpath]`` doesn't exist.
     :raises ValueError: If ``jsonpath`` doesn't begin with "."
+
     """
 
     # These are O(1) reference copies to avoid accidentally modifying source

deckhand/engine/document_validation.py

@@ -138,7 +138,7 @@ class GenericValidator(BaseValidator):
         return errors
 
     def validate(self, document, **kwargs):
-        """Validate ``document``against basic schema validation.
+        """Validate ``document`` against basic schema validation.
 
         Sanity-checks each document for mandatory keys like "metadata" and
         "schema".

deckhand/engine/secrets_manager.py

@@ -372,8 +372,10 @@ class SecretsSubstitution(object):
         :param data: Dictionary of just-rendered document data that belongs
             to the document uniquely identified by ``meta``.
         :type data: dict
-        :returns None
+        :returns: None
+
         """
+
         schema, layer, name = meta
 
         if (schema, name) not in self._substitution_sources:

doc/.gitignore

@@ -0,0 +1,8 @@
+# Sphinx documentation
+api/*
+build/*
+source/_static/*
+source/contributor/api/*
+
+# Files created by releasenotes build
+releasenotes/build

doc/requirements.txt

@@ -5,4 +5,9 @@ sphinx>=1.6.2 # BSD
 sphinx_rtd_theme
 reno>=2.5.0 # Apache-2.0
 plantuml
+sphinxcontrib-apidoc>=0.2.0  # BSD
 
+# NOTE(felipemonteiro): Required by RTD to make oslo.policy and
+# oslo.config sample generation work.
+oslo.config!=4.3.0,!=4.4.0,>=5.2.0 # Apache-2.0
+oslo.policy>=1.33.1 # Apache-2.0

doc/source/conf.py

@@ -39,6 +39,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.apidoc',
     'oslo_policy.sphinxpolicygen',
     # NOTE(fmontei): This is here so that readthedocs can publish releasenotes
     # as well as documentation on the same domain and to do that we use a
@@ -47,6 +48,17 @@ extensions = [
     'reno.sphinxext'
 ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../deckhand'
+apidoc_output_dir = 'contributor/api'
+apidoc_excluded_paths = [
+    'tests/*',
+    'tests',
+    # Avoid directly instantiating the DH service on import.
+    'cmd.py',
+]
+apidoc_separate_modules = True
+
 # oslo_policy.sphinxpolicygen options
 policy_generator_config_file = '../../etc/deckhand/policy-generator.conf'
 sample_policy_basename = '_static/deckhand'

doc/source/contributor/index.rst

@@ -14,8 +14,19 @@
    License for the specific language governing permissions and limitations
    under the License.
 
-Developer's Guide
+Contributor's Guide
-=================
+===================
+
+Contributor Overview
+--------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   developer-overview
+
+Contribution Guidelines
+-----------------------
 
 .. toctree::
    :maxdepth: 2
@@ -23,9 +34,18 @@ Developer's Guide
    HACKING
    REVIEWING
    developer-overview
+
+Other Resources
+---------------
+
+.. toctree::
+   :maxdepth: 3
+
    policy-enforcement
    testing
 
+   Module Reference <api/modules>
+
 Indices and tables
 ------------------
 

doc/source/contributor/policy-enforcement.rst

@@ -39,8 +39,8 @@ exception if the policy action is not registered under ``deckhand.policies``
 means that attempting to enforce anything not found in ``deckhand.policies``
 will error out with a 'Policy not registered' message.
 
-.. automodule:: deckhand.policy
+See `Deckhand's policy module <../contributor/api/deckhand.policy.html>`_ for
-   :members:
+more details.
 
 Sample Policy File
 ==================

doc/source/index.rst

@@ -48,14 +48,6 @@ User's Guide
 
    users/index
 
-Developer's Guide
-=================
-
-.. toctree::
-   :maxdepth: 2
-
-   developers/index
-
 Operator's Guide
 ================
 
@@ -64,6 +56,14 @@ Operator's Guide
 
    operators/index
 
+Contrbitutor's Guide
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   contributor/index
+
 Release Notes
 =============
 

doc/source/operators/api_client.rst

@@ -147,44 +147,4 @@ Client Reference
 ----------------
 
 For more information about how to use the Deckhand client, refer to the
-following documentation:
+`client module <../contributor/api/deckhand.client.html>`_.
-
-.. autoclass:: deckhand.client.client.SessionClient
-    :members:
-
-.. autoclass:: deckhand.client.client.Client
-    :members:
-
-Manager Reference
------------------
-
-For more information about how to use the client managers, refer to the
-following documentation:
-
-.. autoclass:: deckhand.client.buckets.Bucket
-    :members:
-
-.. autoclass:: deckhand.client.buckets.BucketManager
-    :members:
-    :undoc-members:
-
-.. autoclass:: deckhand.client.revisions.Revision
-    :members:
-
-.. autoclass:: deckhand.client.revisions.RevisionManager
-    :members:
-    :undoc-members:
-
-.. autoclass:: deckhand.client.tags.RevisionTag
-    :members:
-
-.. autoclass:: deckhand.client.tags.RevisionTagManager
-    :members:
-    :undoc-members:
-
-.. autoclass:: deckhand.client.validations.Validation
-    :members:
-
-.. autoclass:: deckhand.client.validations.ValidationManager
-    :members:
-    :undoc-members:

doc/source/operators/exceptions.rst

@@ -17,95 +17,6 @@
 Deckhand Exceptions
 ===================
 
-.. autoexception:: deckhand.errors.BarbicanClientException
+For a list of Deckhand exceptions as well as debugging information related to
-   :members:
+each please reference
-   :show-inheritance:
+`Deckhand's errors module <../contributor/api/deckhand.errors.html>`_.
-   :undoc-members:
-.. autoexception:: deckhand.errors.BarbicanServerException
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.DeepDiffException
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.DocumentNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.DuplicateDocumentExists
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.EncryptionSourceNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.InvalidDocumentFormat
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.IndeterminateDocumentParent
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.InvalidInputException
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.LayeringPolicyNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.MissingDocumentKey
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.MissingDocumentPattern
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.PolicyNotAuthorized
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.RevisionTagBadFormat
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.RevisionTagNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.RevisionNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.SingletonDocumentConflict
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.SubstitutionDependencyCycle
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.SubstitutionSourceDataNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.SubstitutionSourceNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.UnknownSubstitutionError
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.UnsupportedActionMethod
-   :members:
-   :show-inheritance:
-   :undoc-members:
-.. autoexception:: deckhand.errors.ValidationNotFound
-   :members:
-   :show-inheritance:
-   :undoc-members:

doc/source/users/validation.rst

@@ -189,13 +189,6 @@ For post-rendering validation, 2 types of behavior are possible:
 #. Failure to validate post-rendered documents results in a 500 Internal Server
    Error getting raised.
 
-Validation Module
------------------
-
-.. autoclass:: deckhand.engine.document_validation.DocumentValidation
-   :members:
-   :private-members:
-
 .. _schemas:
 
 Validation Schemas

tools/build-docs.sh

@@ -11,6 +11,6 @@ python -m plantuml doc/source/diagrams/*.uml
 mv doc/source/diagrams/*.png doc/source/images
 
 # Generate documentation.
-rm -rf doc/build
+rm -rf doc/build doc/source/contributor/api/ releasenotes/build
-rm -rf releasenotes/build
+sphinx-apidoc -o doc/api deckhand
 sphinx-build -W -b html doc/source doc/build/html