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
This commit is contained in:
Felipe Monteiro 2018-10-27 16:43:55 -04:00
parent 018162f1ef
commit 9d91a072cd
18 changed files with 70 additions and 160 deletions

4
.gitignore vendored
View File

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

View File

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

View File

@ -138,7 +138,7 @@ class GenericValidator(BaseValidator):
return errors return errors
def validate(self, document, **kwargs): 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 Sanity-checks each document for mandatory keys like "metadata" and
"schema". "schema".

View File

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

8
doc/.gitignore vendored Normal file
View File

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

View File

@ -5,4 +5,9 @@ sphinx>=1.6.2 # BSD
sphinx_rtd_theme sphinx_rtd_theme
reno>=2.5.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0
plantuml 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

View File

@ -39,6 +39,7 @@ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.viewcode', 'sphinx.ext.viewcode',
'sphinxcontrib.apidoc',
'oslo_policy.sphinxpolicygen', 'oslo_policy.sphinxpolicygen',
# NOTE(fmontei): This is here so that readthedocs can publish releasenotes # 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 # as well as documentation on the same domain and to do that we use a
@ -47,6 +48,17 @@ extensions = [
'reno.sphinxext' '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 # oslo_policy.sphinxpolicygen options
policy_generator_config_file = '../../etc/deckhand/policy-generator.conf' policy_generator_config_file = '../../etc/deckhand/policy-generator.conf'
sample_policy_basename = '_static/deckhand' sample_policy_basename = '_static/deckhand'

View File

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

View File

@ -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`` means that attempting to enforce anything not found in ``deckhand.policies``
will error out with a 'Policy not registered' message. 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 Sample Policy File
================== ==================

View File

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

View File

@ -147,44 +147,4 @@ Client Reference
---------------- ----------------
For more information about how to use the Deckhand client, refer to the 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:

View File

@ -17,95 +17,6 @@
Deckhand Exceptions 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:

View File

@ -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 #. Failure to validate post-rendered documents results in a 500 Internal Server
Error getting raised. Error getting raised.
Validation Module
-----------------
.. autoclass:: deckhand.engine.document_validation.DocumentValidation
:members:
:private-members:
.. _schemas: .. _schemas:
Validation Schemas Validation Schemas

View File

@ -11,6 +11,6 @@ python -m plantuml doc/source/diagrams/*.uml
mv doc/source/diagrams/*.png doc/source/images mv doc/source/diagrams/*.png doc/source/images
# Generate documentation. # 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 sphinx-build -W -b html doc/source doc/build/html