Merge "docs: Use sphinx-apidoc library for autodoc compatibility"
This commit is contained in:
commit
a5deb49e7e
|
@ -66,10 +66,6 @@ instance/
|
||||||
# Scrapy stuff:
|
# Scrapy stuff:
|
||||||
.scrapy
|
.scrapy
|
||||||
|
|
||||||
# Sphinx documentation
|
|
||||||
doc/_build/
|
|
||||||
doc/source/_static/
|
|
||||||
|
|
||||||
# PyBuilder
|
# PyBuilder
|
||||||
target/
|
target/
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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".
|
||||||
|
|
|
@ -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:
|
||||||
|
|
|
@ -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
|
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
|
# NOTE(felipemonteiro): Required by RTD to make oslo.policy and
|
||||||
# oslo.config sample generation work.
|
# oslo.config sample generation work.
|
||||||
|
|
|
@ -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'
|
||||||
|
|
|
@ -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
|
||||||
------------------
|
------------------
|
||||||
|
|
|
@ -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
|
||||||
==================
|
==================
|
|
@ -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
|
||||||
=============
|
=============
|
||||||
|
|
||||||
|
|
|
@ -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:
|
|
||||||
|
|
|
@ -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:
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue