From 9d91a072cd65ee37068c6c06a40eac276f3b751a Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Sat, 27 Oct 2018 16:43:55 -0400 Subject: [PATCH] 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 | 4 - deckhand/common/utils.py | 3 + deckhand/engine/document_validation.py | 2 +- deckhand/engine/secrets_manager.py | 4 +- doc/.gitignore | 8 ++ doc/requirements.txt | 5 + doc/source/conf.py | 12 +++ .../{developers => contributor}/HACKING.rst | 0 .../{developers => contributor}/REVIEWING.rst | 0 .../developer-overview.rst | 0 .../{developers => contributor}/index.rst | 24 ++++- .../policy-enforcement.rst | 4 +- .../{developers => contributor}/testing.rst | 0 doc/source/index.rst | 16 ++-- doc/source/operators/api_client.rst | 42 +------- doc/source/operators/exceptions.rst | 95 +------------------ doc/source/users/validation.rst | 7 -- tools/build-docs.sh | 4 +- 18 files changed, 70 insertions(+), 160 deletions(-) create mode 100644 doc/.gitignore rename doc/source/{developers => contributor}/HACKING.rst (100%) rename doc/source/{developers => contributor}/REVIEWING.rst (100%) rename doc/source/{developers => contributor}/developer-overview.rst (100%) rename doc/source/{developers => contributor}/index.rst (74%) rename doc/source/{developers => contributor}/policy-enforcement.rst (96%) rename doc/source/{developers => contributor}/testing.rst (100%) 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