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
# Sphinx documentation
doc/_build/
doc/source/_static/
# PyBuilder
target/

View File

@ -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

View File

@ -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".

View File

@ -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:

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
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

View File

@ -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'

View File

@ -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
------------------

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``
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
==================

View File

@ -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
=============

View File

@ -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>`_.

View File

@ -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>`_.

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
Error getting raised.
Validation Module
-----------------
.. autoclass:: deckhand.engine.document_validation.DocumentValidation
:members:
:private-members:
.. _schemas:
Validation Schemas

View File

@ -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