Merge "docs: Use sphinx-apidoc library for autodoc compatibility"

This commit is contained in:
Zuul 2018-10-27 23:00:16 +00:00 committed by Gerrit Code Review
commit a5deb49e7e
18 changed files with 66 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,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.

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