diff --git a/.gitignore b/.gitignore index d7f77b3e..dc508da3 100644 --- a/.gitignore +++ b/.gitignore @@ -66,10 +66,6 @@ instance/ # Scrapy stuff: .scrapy -# Sphinx documentation -doc/_build/ -doc/source/_static/ - # PyBuilder target/ diff --git a/deckhand/common/utils.py b/deckhand/common/utils.py index eed2f8f3..26473e00 100644 --- a/deckhand/common/utils.py +++ b/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 diff --git a/deckhand/engine/document_validation.py b/deckhand/engine/document_validation.py index 4b70f893..d9947810 100644 --- a/deckhand/engine/document_validation.py +++ b/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". diff --git a/deckhand/engine/secrets_manager.py b/deckhand/engine/secrets_manager.py index 0ef1081f..3a726318 100644 --- a/deckhand/engine/secrets_manager.py +++ b/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: diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..340c2925 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,8 @@ +# Sphinx documentation +api/* +build/* +source/_static/* +source/contributor/api/* + +# Files created by releasenotes build +releasenotes/build diff --git a/doc/requirements.txt b/doc/requirements.txt index f9e6b367..08ab488f 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 399dc0a6..3954a927 100644 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/source/developers/HACKING.rst b/doc/source/contributor/HACKING.rst similarity index 100% rename from doc/source/developers/HACKING.rst rename to doc/source/contributor/HACKING.rst diff --git a/doc/source/developers/REVIEWING.rst b/doc/source/contributor/REVIEWING.rst similarity index 100% rename from doc/source/developers/REVIEWING.rst rename to doc/source/contributor/REVIEWING.rst diff --git a/doc/source/developers/developer-overview.rst b/doc/source/contributor/developer-overview.rst similarity index 100% rename from doc/source/developers/developer-overview.rst rename to doc/source/contributor/developer-overview.rst diff --git a/doc/source/developers/index.rst b/doc/source/contributor/index.rst similarity index 74% rename from doc/source/developers/index.rst rename to doc/source/contributor/index.rst index 37304de9..65dd5f6a 100644 --- a/doc/source/developers/index.rst +++ b/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 + Indices and tables ------------------ diff --git a/doc/source/developers/policy-enforcement.rst b/doc/source/contributor/policy-enforcement.rst similarity index 96% rename from doc/source/developers/policy-enforcement.rst rename to doc/source/contributor/policy-enforcement.rst index b9e21d9a..d90f4b41 100644 --- a/doc/source/developers/policy-enforcement.rst +++ b/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 - :members: +See `Deckhand's policy module <../contributor/api/deckhand.policy.html>`_ for +more details. Sample Policy File ================== diff --git a/doc/source/developers/testing.rst b/doc/source/contributor/testing.rst similarity index 100% rename from doc/source/developers/testing.rst rename to doc/source/contributor/testing.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 3de5ab49..d4ea1f79 100644 --- a/doc/source/index.rst +++ b/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 ============= diff --git a/doc/source/operators/api_client.rst b/doc/source/operators/api_client.rst index 61dedca0..c132511b 100644 --- a/doc/source/operators/api_client.rst +++ b/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: - -.. 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: +`client module <../contributor/api/deckhand.client.html>`_. diff --git a/doc/source/operators/exceptions.rst b/doc/source/operators/exceptions.rst index 2e086c70..aba81370 100644 --- a/doc/source/operators/exceptions.rst +++ b/doc/source/operators/exceptions.rst @@ -17,95 +17,6 @@ Deckhand Exceptions =================== -.. autoexception:: deckhand.errors.BarbicanClientException - :members: - :show-inheritance: - :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: +For a list of Deckhand exceptions as well as debugging information related to +each please reference +`Deckhand's errors module <../contributor/api/deckhand.errors.html>`_. diff --git a/doc/source/users/validation.rst b/doc/source/users/validation.rst index e58a372e..ac47e96b 100644 --- a/doc/source/users/validation.rst +++ b/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 diff --git a/tools/build-docs.sh b/tools/build-docs.sh index 35d42447..ec2e4372 100755 --- a/tools/build-docs.sh +++ b/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 releasenotes/build +rm -rf doc/build doc/source/contributor/api/ releasenotes/build +sphinx-apidoc -o doc/api deckhand sphinx-build -W -b html doc/source doc/build/html