Merge "docs: Use sphinx-apidoc library for autodoc compatibility"
This commit is contained in:
commit
a5deb49e7e
|
@ -66,10 +66,6 @@ instance/
|
|||
# Scrapy stuff:
|
||||
.scrapy
|
||||
|
||||
# Sphinx documentation
|
||||
doc/_build/
|
||||
doc/source/_static/
|
||||
|
||||
# PyBuilder
|
||||
target/
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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".
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -0,0 +1,8 @@
|
|||
# Sphinx documentation
|
||||
api/*
|
||||
build/*
|
||||
source/_static/*
|
||||
source/contributor/api/*
|
||||
|
||||
# Files created by releasenotes build
|
||||
releasenotes/build
|
|
@ -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.
|
||||
|
|
|
@ -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'
|
||||
|
|
|
@ -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
|
||||
------------------
|
||||
|
|
@ -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
|
||||
==================
|
|
@ -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
|
||||
=============
|
||||
|
||||
|
|
|
@ -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>`_.
|
||||
|
|
|
@ -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>`_.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue