summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFelipe Monteiro <felipe.monteiro@att.com>2018-10-27 16:43:55 -0400
committerFelipe Monteiro <felipe.monteiro@att.com>2018-10-27 22:52:39 +0100
commit9d91a072cd65ee37068c6c06a40eac276f3b751a (patch)
treef276c4363d8b55fa5a9c2de86c02981ee580ad61
parent018162f1ef6f1813454e113ab5679ca5086460d3 (diff)
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
Notes
Notes (review): Code-Review+2: Felipe Monteiro <felipe.monteiro@att.com> Workflow+1: Felipe Monteiro <felipe.monteiro@att.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Sat, 27 Oct 2018 23:00:16 +0000 Reviewed-on: https://review.openstack.org/613761 Project: openstack/airship-deckhand Branch: refs/heads/master
-rw-r--r--.gitignore4
-rw-r--r--deckhand/common/utils.py3
-rw-r--r--deckhand/engine/document_validation.py2
-rw-r--r--deckhand/engine/secrets_manager.py4
-rw-r--r--doc/.gitignore8
-rw-r--r--doc/requirements.txt5
-rw-r--r--doc/source/conf.py12
-rw-r--r--doc/source/contributor/HACKING.rst (renamed from doc/source/developers/HACKING.rst)0
-rw-r--r--doc/source/contributor/REVIEWING.rst (renamed from doc/source/developers/REVIEWING.rst)0
-rw-r--r--doc/source/contributor/developer-overview.rst (renamed from doc/source/developers/developer-overview.rst)0
-rw-r--r--doc/source/contributor/index.rst (renamed from doc/source/developers/index.rst)24
-rw-r--r--doc/source/contributor/policy-enforcement.rst (renamed from doc/source/developers/policy-enforcement.rst)4
-rw-r--r--doc/source/contributor/testing.rst (renamed from doc/source/developers/testing.rst)0
-rw-r--r--doc/source/index.rst12
-rw-r--r--doc/source/operators/api_client.rst42
-rw-r--r--doc/source/operators/exceptions.rst95
-rw-r--r--doc/source/users/validation.rst7
-rwxr-xr-xtools/build-docs.sh4
18 files changed, 68 insertions, 158 deletions
diff --git a/.gitignore b/.gitignore
index d7f77b3..dc508da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -66,10 +66,6 @@ instance/
66# Scrapy stuff: 66# Scrapy stuff:
67.scrapy 67.scrapy
68 68
69# Sphinx documentation
70doc/_build/
71doc/source/_static/
72
73# PyBuilder 69# PyBuilder
74target/ 70target/
75 71
diff --git a/deckhand/common/utils.py b/deckhand/common/utils.py
index eed2f8f..26473e0 100644
--- a/deckhand/common/utils.py
+++ b/deckhand/common/utils.py
@@ -212,11 +212,13 @@ def _execute_data_expansion(data, jsonpath):
212 212
213def jsonpath_replace(data, value, jsonpath, pattern=None, recurse=None): 213def jsonpath_replace(data, value, jsonpath, pattern=None, recurse=None):
214 """Update value in ``data`` at the path specified by ``jsonpath``. 214 """Update value in ``data`` at the path specified by ``jsonpath``.
215
215 If the nested path corresponding to ``jsonpath`` isn't found in ``data``, 216 If the nested path corresponding to ``jsonpath`` isn't found in ``data``,
216 the path is created as an empty ``{}`` for each sub-path along the 217 the path is created as an empty ``{}`` for each sub-path along the
217 ``jsonpath``. 218 ``jsonpath``.
218 219
219 Example:: 220 Example::
221
220 doc = { 222 doc = {
221 'data': { 223 'data': {
222 'some_url': http://admin:INSERT_PASSWORD_HERE@svc-name:8080/v1 224 '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):
248 :raises: MissingDocumentPattern if ``pattern`` is not None and 250 :raises: MissingDocumentPattern if ``pattern`` is not None and
249 ``data[jsonpath]`` doesn't exist. 251 ``data[jsonpath]`` doesn't exist.
250 :raises ValueError: If ``jsonpath`` doesn't begin with "." 252 :raises ValueError: If ``jsonpath`` doesn't begin with "."
253
251 """ 254 """
252 255
253 # These are O(1) reference copies to avoid accidentally modifying source 256 # These are O(1) reference copies to avoid accidentally modifying source
diff --git a/deckhand/engine/document_validation.py b/deckhand/engine/document_validation.py
index 4b70f89..d994781 100644
--- a/deckhand/engine/document_validation.py
+++ b/deckhand/engine/document_validation.py
@@ -138,7 +138,7 @@ class GenericValidator(BaseValidator):
138 return errors 138 return errors
139 139
140 def validate(self, document, **kwargs): 140 def validate(self, document, **kwargs):
141 """Validate ``document``against basic schema validation. 141 """Validate ``document`` against basic schema validation.
142 142
143 Sanity-checks each document for mandatory keys like "metadata" and 143 Sanity-checks each document for mandatory keys like "metadata" and
144 "schema". 144 "schema".
diff --git a/deckhand/engine/secrets_manager.py b/deckhand/engine/secrets_manager.py
index 0ef1081..3a72631 100644
--- a/deckhand/engine/secrets_manager.py
+++ b/deckhand/engine/secrets_manager.py
@@ -372,8 +372,10 @@ class SecretsSubstitution(object):
372 :param data: Dictionary of just-rendered document data that belongs 372 :param data: Dictionary of just-rendered document data that belongs
373 to the document uniquely identified by ``meta``. 373 to the document uniquely identified by ``meta``.
374 :type data: dict 374 :type data: dict
375 :returns None 375 :returns: None
376
376 """ 377 """
378
377 schema, layer, name = meta 379 schema, layer, name = meta
378 380
379 if (schema, name) not in self._substitution_sources: 381 if (schema, name) not in self._substitution_sources:
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..340c292
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,8 @@
1# Sphinx documentation
2api/*
3build/*
4source/_static/*
5source/contributor/api/*
6
7# Files created by releasenotes build
8releasenotes/build
diff --git a/doc/requirements.txt b/doc/requirements.txt
index f9e6b36..08ab488 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -5,4 +5,9 @@ sphinx>=1.6.2 # BSD
5sphinx_rtd_theme 5sphinx_rtd_theme
6reno>=2.5.0 # Apache-2.0 6reno>=2.5.0 # Apache-2.0
7plantuml 7plantuml
8sphinxcontrib-apidoc>=0.2.0 # BSD
8 9
10# NOTE(felipemonteiro): Required by RTD to make oslo.policy and
11# oslo.config sample generation work.
12oslo.config!=4.3.0,!=4.4.0,>=5.2.0 # Apache-2.0
13oslo.policy>=1.33.1 # Apache-2.0
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 399dc0a..3954a92 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -39,6 +39,7 @@ extensions = [
39 'sphinx.ext.autodoc', 39 'sphinx.ext.autodoc',
40 'sphinx.ext.todo', 40 'sphinx.ext.todo',
41 'sphinx.ext.viewcode', 41 'sphinx.ext.viewcode',
42 'sphinxcontrib.apidoc',
42 'oslo_policy.sphinxpolicygen', 43 'oslo_policy.sphinxpolicygen',
43 # NOTE(fmontei): This is here so that readthedocs can publish releasenotes 44 # NOTE(fmontei): This is here so that readthedocs can publish releasenotes
44 # as well as documentation on the same domain and to do that we use a 45 # as well as documentation on the same domain and to do that we use a
@@ -47,6 +48,17 @@ extensions = [
47 'reno.sphinxext' 48 'reno.sphinxext'
48] 49]
49 50
51# sphinxcontrib.apidoc options
52apidoc_module_dir = '../../deckhand'
53apidoc_output_dir = 'contributor/api'
54apidoc_excluded_paths = [
55 'tests/*',
56 'tests',
57 # Avoid directly instantiating the DH service on import.
58 'cmd.py',
59]
60apidoc_separate_modules = True
61
50# oslo_policy.sphinxpolicygen options 62# oslo_policy.sphinxpolicygen options
51policy_generator_config_file = '../../etc/deckhand/policy-generator.conf' 63policy_generator_config_file = '../../etc/deckhand/policy-generator.conf'
52sample_policy_basename = '_static/deckhand' 64sample_policy_basename = '_static/deckhand'
diff --git a/doc/source/developers/HACKING.rst b/doc/source/contributor/HACKING.rst
index 93a7710..93a7710 100644
--- a/doc/source/developers/HACKING.rst
+++ b/doc/source/contributor/HACKING.rst
diff --git a/doc/source/developers/REVIEWING.rst b/doc/source/contributor/REVIEWING.rst
index 4d1b00f..4d1b00f 100644
--- a/doc/source/developers/REVIEWING.rst
+++ b/doc/source/contributor/REVIEWING.rst
diff --git a/doc/source/developers/developer-overview.rst b/doc/source/contributor/developer-overview.rst
index 718ec62..718ec62 100644
--- a/doc/source/developers/developer-overview.rst
+++ b/doc/source/contributor/developer-overview.rst
diff --git a/doc/source/developers/index.rst b/doc/source/contributor/index.rst
index 37304de..65dd5f6 100644
--- a/doc/source/developers/index.rst
+++ b/doc/source/contributor/index.rst
@@ -14,8 +14,19 @@
14 License for the specific language governing permissions and limitations 14 License for the specific language governing permissions and limitations
15 under the License. 15 under the License.
16 16
17Developer's Guide 17Contributor's Guide
18================= 18===================
19
20Contributor Overview
21--------------------
22
23.. toctree::
24 :maxdepth: 2
25
26 developer-overview
27
28Contribution Guidelines
29-----------------------
19 30
20.. toctree:: 31.. toctree::
21 :maxdepth: 2 32 :maxdepth: 2
@@ -23,9 +34,18 @@ Developer's Guide
23 HACKING 34 HACKING
24 REVIEWING 35 REVIEWING
25 developer-overview 36 developer-overview
37
38Other Resources
39---------------
40
41.. toctree::
42 :maxdepth: 3
43
26 policy-enforcement 44 policy-enforcement
27 testing 45 testing
28 46
47 Module Reference <api/modules>
48
29Indices and tables 49Indices and tables
30------------------ 50------------------
31 51
diff --git a/doc/source/developers/policy-enforcement.rst b/doc/source/contributor/policy-enforcement.rst
index b9e21d9..d90f4b4 100644
--- a/doc/source/developers/policy-enforcement.rst
+++ b/doc/source/contributor/policy-enforcement.rst
@@ -39,8 +39,8 @@ exception if the policy action is not registered under ``deckhand.policies``
39means that attempting to enforce anything not found in ``deckhand.policies`` 39means that attempting to enforce anything not found in ``deckhand.policies``
40will error out with a 'Policy not registered' message. 40will error out with a 'Policy not registered' message.
41 41
42.. automodule:: deckhand.policy 42See `Deckhand's policy module <../contributor/api/deckhand.policy.html>`_ for
43 :members: 43more details.
44 44
45Sample Policy File 45Sample Policy File
46================== 46==================
diff --git a/doc/source/developers/testing.rst b/doc/source/contributor/testing.rst
index e154191..e154191 100644
--- a/doc/source/developers/testing.rst
+++ b/doc/source/contributor/testing.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3de5ab4..d4ea1f7 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -48,21 +48,21 @@ User's Guide
48 48
49 users/index 49 users/index
50 50
51Developer's Guide 51Operator's Guide
52================= 52================
53 53
54.. toctree:: 54.. toctree::
55 :maxdepth: 2 55 :maxdepth: 2
56 56
57 developers/index 57 operators/index
58 58
59Operator's Guide 59Contrbitutor's Guide
60================ 60====================
61 61
62.. toctree:: 62.. toctree::
63 :maxdepth: 2 63 :maxdepth: 2
64 64
65 operators/index 65 contributor/index
66 66
67Release Notes 67Release Notes
68============= 68=============
diff --git a/doc/source/operators/api_client.rst b/doc/source/operators/api_client.rst
index 61dedca..c132511 100644
--- a/doc/source/operators/api_client.rst
+++ b/doc/source/operators/api_client.rst
@@ -147,44 +147,4 @@ Client Reference
147---------------- 147----------------
148 148
149For more information about how to use the Deckhand client, refer to the 149For more information about how to use the Deckhand client, refer to the
150following documentation: 150`client module <../contributor/api/deckhand.client.html>`_.
151
152.. autoclass:: deckhand.client.client.SessionClient
153 :members:
154
155.. autoclass:: deckhand.client.client.Client
156 :members:
157
158Manager Reference
159-----------------
160
161For more information about how to use the client managers, refer to the
162following documentation:
163
164.. autoclass:: deckhand.client.buckets.Bucket
165 :members:
166
167.. autoclass:: deckhand.client.buckets.BucketManager
168 :members:
169 :undoc-members:
170
171.. autoclass:: deckhand.client.revisions.Revision
172 :members:
173
174.. autoclass:: deckhand.client.revisions.RevisionManager
175 :members:
176 :undoc-members:
177
178.. autoclass:: deckhand.client.tags.RevisionTag
179 :members:
180
181.. autoclass:: deckhand.client.tags.RevisionTagManager
182 :members:
183 :undoc-members:
184
185.. autoclass:: deckhand.client.validations.Validation
186 :members:
187
188.. autoclass:: deckhand.client.validations.ValidationManager
189 :members:
190 :undoc-members:
diff --git a/doc/source/operators/exceptions.rst b/doc/source/operators/exceptions.rst
index 2e086c7..aba8137 100644
--- a/doc/source/operators/exceptions.rst
+++ b/doc/source/operators/exceptions.rst
@@ -17,95 +17,6 @@
17Deckhand Exceptions 17Deckhand Exceptions
18=================== 18===================
19 19
20.. autoexception:: deckhand.errors.BarbicanClientException 20For a list of Deckhand exceptions as well as debugging information related to
21 :members: 21each please reference
22 :show-inheritance: 22`Deckhand's errors module <../contributor/api/deckhand.errors.html>`_.
23 :undoc-members:
24.. autoexception:: deckhand.errors.BarbicanServerException
25 :members:
26 :show-inheritance:
27 :undoc-members:
28.. autoexception:: deckhand.errors.DeepDiffException
29 :members:
30 :show-inheritance:
31 :undoc-members:
32.. autoexception:: deckhand.errors.DocumentNotFound
33 :members:
34 :show-inheritance:
35 :undoc-members:
36.. autoexception:: deckhand.errors.DuplicateDocumentExists
37 :members:
38 :show-inheritance:
39 :undoc-members:
40.. autoexception:: deckhand.errors.EncryptionSourceNotFound
41 :members:
42 :show-inheritance:
43 :undoc-members:
44.. autoexception:: deckhand.errors.InvalidDocumentFormat
45 :members:
46 :show-inheritance:
47 :undoc-members:
48.. autoexception:: deckhand.errors.IndeterminateDocumentParent
49 :members:
50 :show-inheritance:
51 :undoc-members:
52.. autoexception:: deckhand.errors.InvalidInputException
53 :members:
54 :show-inheritance:
55 :undoc-members:
56.. autoexception:: deckhand.errors.LayeringPolicyNotFound
57 :members:
58 :show-inheritance:
59 :undoc-members:
60.. autoexception:: deckhand.errors.MissingDocumentKey
61 :members:
62 :show-inheritance:
63 :undoc-members:
64.. autoexception:: deckhand.errors.MissingDocumentPattern
65 :members:
66 :show-inheritance:
67 :undoc-members:
68.. autoexception:: deckhand.errors.PolicyNotAuthorized
69 :members:
70 :show-inheritance:
71 :undoc-members:
72.. autoexception:: deckhand.errors.RevisionTagBadFormat
73 :members:
74 :show-inheritance:
75 :undoc-members:
76.. autoexception:: deckhand.errors.RevisionTagNotFound
77 :members:
78 :show-inheritance:
79 :undoc-members:
80.. autoexception:: deckhand.errors.RevisionNotFound
81 :members:
82 :show-inheritance:
83 :undoc-members:
84.. autoexception:: deckhand.errors.SingletonDocumentConflict
85 :members:
86 :show-inheritance:
87 :undoc-members:
88.. autoexception:: deckhand.errors.SubstitutionDependencyCycle
89 :members:
90 :show-inheritance:
91 :undoc-members:
92.. autoexception:: deckhand.errors.SubstitutionSourceDataNotFound
93 :members:
94 :show-inheritance:
95 :undoc-members:
96.. autoexception:: deckhand.errors.SubstitutionSourceNotFound
97 :members:
98 :show-inheritance:
99 :undoc-members:
100.. autoexception:: deckhand.errors.UnknownSubstitutionError
101 :members:
102 :show-inheritance:
103 :undoc-members:
104.. autoexception:: deckhand.errors.UnsupportedActionMethod
105 :members:
106 :show-inheritance:
107 :undoc-members:
108.. autoexception:: deckhand.errors.ValidationNotFound
109 :members:
110 :show-inheritance:
111 :undoc-members:
diff --git a/doc/source/users/validation.rst b/doc/source/users/validation.rst
index e58a372..ac47e96 100644
--- a/doc/source/users/validation.rst
+++ b/doc/source/users/validation.rst
@@ -189,13 +189,6 @@ For post-rendering validation, 2 types of behavior are possible:
189#. Failure to validate post-rendered documents results in a 500 Internal Server 189#. Failure to validate post-rendered documents results in a 500 Internal Server
190 Error getting raised. 190 Error getting raised.
191 191
192Validation Module
193-----------------
194
195.. autoclass:: deckhand.engine.document_validation.DocumentValidation
196 :members:
197 :private-members:
198
199.. _schemas: 192.. _schemas:
200 193
201Validation Schemas 194Validation Schemas
diff --git a/tools/build-docs.sh b/tools/build-docs.sh
index 35d4244..ec2e437 100755
--- a/tools/build-docs.sh
+++ b/tools/build-docs.sh
@@ -11,6 +11,6 @@ python -m plantuml doc/source/diagrams/*.uml
11mv doc/source/diagrams/*.png doc/source/images 11mv doc/source/diagrams/*.png doc/source/images
12 12
13# Generate documentation. 13# Generate documentation.
14rm -rf doc/build 14rm -rf doc/build doc/source/contributor/api/ releasenotes/build
15rm -rf releasenotes/build 15sphinx-apidoc -o doc/api deckhand
16sphinx-build -W -b html doc/source doc/build/html 16sphinx-build -W -b html doc/source doc/build/html