Merge "docs: Use sphinx-apidoc library for autodoc compatibility"

.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,6 +5,7 @@ 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.

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