Browse Source

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

changes/22/610722/3
Zuul 8 months ago
parent
commit
a5deb49e7e

+ 0
- 4
.gitignore View File

@@ -66,10 +66,6 @@ instance/
66 66
 # Scrapy stuff:
67 67
 .scrapy
68 68
 
69
-# Sphinx documentation
70
-doc/_build/
71
-doc/source/_static/
72
-
73 69
 # PyBuilder
74 70
 target/
75 71
 

+ 3
- 0
deckhand/common/utils.py View File

@@ -212,11 +212,13 @@ def _execute_data_expansion(data, jsonpath):
212 212
 
213 213
 def jsonpath_replace(data, value, jsonpath, pattern=None, recurse=None):
214 214
     """Update value in ``data`` at the path specified by ``jsonpath``.
215
+
215 216
     If the nested path corresponding to ``jsonpath`` isn't found in ``data``,
216 217
     the path is created as an empty ``{}`` for each sub-path along the
217 218
     ``jsonpath``.
218 219
 
219 220
     Example::
221
+
220 222
         doc = {
221 223
             'data': {
222 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 250
     :raises: MissingDocumentPattern if ``pattern`` is not None and
249 251
         ``data[jsonpath]`` doesn't exist.
250 252
     :raises ValueError: If ``jsonpath`` doesn't begin with "."
253
+
251 254
     """
252 255
 
253 256
     # These are O(1) reference copies to avoid accidentally modifying source

+ 1
- 1
deckhand/engine/document_validation.py View File

@@ -138,7 +138,7 @@ class GenericValidator(BaseValidator):
138 138
         return errors
139 139
 
140 140
     def validate(self, document, **kwargs):
141
-        """Validate ``document``against basic schema validation.
141
+        """Validate ``document`` against basic schema validation.
142 142
 
143 143
         Sanity-checks each document for mandatory keys like "metadata" and
144 144
         "schema".

+ 3
- 1
deckhand/engine/secrets_manager.py View File

@@ -372,8 +372,10 @@ class SecretsSubstitution(object):
372 372
         :param data: Dictionary of just-rendered document data that belongs
373 373
             to the document uniquely identified by ``meta``.
374 374
         :type data: dict
375
-        :returns None
375
+        :returns: None
376
+
376 377
         """
378
+
377 379
         schema, layer, name = meta
378 380
 
379 381
         if (schema, name) not in self._substitution_sources:

+ 8
- 0
doc/.gitignore View File

@@ -0,0 +1,8 @@
1
+# Sphinx documentation
2
+api/*
3
+build/*
4
+source/_static/*
5
+source/contributor/api/*
6
+
7
+# Files created by releasenotes build
8
+releasenotes/build

+ 1
- 0
doc/requirements.txt View File

@@ -5,6 +5,7 @@ sphinx>=1.6.2 # BSD
5 5
 sphinx_rtd_theme
6 6
 reno>=2.5.0 # Apache-2.0
7 7
 plantuml
8
+sphinxcontrib-apidoc>=0.2.0  # BSD
8 9
 
9 10
 # NOTE(felipemonteiro): Required by RTD to make oslo.policy and
10 11
 # oslo.config sample generation work.

+ 12
- 0
doc/source/conf.py View File

@@ -39,6 +39,7 @@ extensions = [
39 39
     'sphinx.ext.autodoc',
40 40
     'sphinx.ext.todo',
41 41
     'sphinx.ext.viewcode',
42
+    'sphinxcontrib.apidoc',
42 43
     'oslo_policy.sphinxpolicygen',
43 44
     # NOTE(fmontei): This is here so that readthedocs can publish releasenotes
44 45
     # as well as documentation on the same domain and to do that we use a
@@ -47,6 +48,17 @@ extensions = [
47 48
     'reno.sphinxext'
48 49
 ]
49 50
 
51
+# sphinxcontrib.apidoc options
52
+apidoc_module_dir = '../../deckhand'
53
+apidoc_output_dir = 'contributor/api'
54
+apidoc_excluded_paths = [
55
+    'tests/*',
56
+    'tests',
57
+    # Avoid directly instantiating the DH service on import.
58
+    'cmd.py',
59
+]
60
+apidoc_separate_modules = True
61
+
50 62
 # oslo_policy.sphinxpolicygen options
51 63
 policy_generator_config_file = '../../etc/deckhand/policy-generator.conf'
52 64
 sample_policy_basename = '_static/deckhand'

doc/source/developers/HACKING.rst → doc/source/contributor/HACKING.rst View File


doc/source/developers/REVIEWING.rst → doc/source/contributor/REVIEWING.rst View File


doc/source/developers/developer-overview.rst → doc/source/contributor/developer-overview.rst View File


doc/source/developers/index.rst → doc/source/contributor/index.rst View File

@@ -14,8 +14,19 @@
14 14
    License for the specific language governing permissions and limitations
15 15
    under the License.
16 16
 
17
-Developer's Guide
18
-=================
17
+Contributor's Guide
18
+===================
19
+
20
+Contributor Overview
21
+--------------------
22
+
23
+.. toctree::
24
+   :maxdepth: 2
25
+
26
+   developer-overview
27
+
28
+Contribution Guidelines
29
+-----------------------
19 30
 
20 31
 .. toctree::
21 32
    :maxdepth: 2
@@ -23,9 +34,18 @@ Developer's Guide
23 34
    HACKING
24 35
    REVIEWING
25 36
    developer-overview
37
+
38
+Other Resources
39
+---------------
40
+
41
+.. toctree::
42
+   :maxdepth: 3
43
+
26 44
    policy-enforcement
27 45
    testing
28 46
 
47
+   Module Reference <api/modules>
48
+
29 49
 Indices and tables
30 50
 ------------------
31 51
 

doc/source/developers/policy-enforcement.rst → doc/source/contributor/policy-enforcement.rst View File

@@ -39,8 +39,8 @@ exception if the policy action is not registered under ``deckhand.policies``
39 39
 means that attempting to enforce anything not found in ``deckhand.policies``
40 40
 will error out with a 'Policy not registered' message.
41 41
 
42
-.. automodule:: deckhand.policy
43
-   :members:
42
+See `Deckhand's policy module <../contributor/api/deckhand.policy.html>`_ for
43
+more details.
44 44
 
45 45
 Sample Policy File
46 46
 ==================

doc/source/developers/testing.rst → doc/source/contributor/testing.rst View File


+ 6
- 6
doc/source/index.rst View File

@@ -48,21 +48,21 @@ User's Guide
48 48
 
49 49
    users/index
50 50
 
51
-Developer's Guide
52
-=================
51
+Operator's Guide
52
+================
53 53
 
54 54
 .. toctree::
55 55
    :maxdepth: 2
56 56
 
57
-   developers/index
57
+   operators/index
58 58
 
59
-Operator's Guide
60
-================
59
+Contrbitutor's Guide
60
+====================
61 61
 
62 62
 .. toctree::
63 63
    :maxdepth: 2
64 64
 
65
-   operators/index
65
+   contributor/index
66 66
 
67 67
 Release Notes
68 68
 =============

+ 1
- 41
doc/source/operators/api_client.rst View File

@@ -147,44 +147,4 @@ Client Reference
147 147
 ----------------
148 148
 
149 149
 For more information about how to use the Deckhand client, refer to the
150
-following documentation:
151
-
152
-.. autoclass:: deckhand.client.client.SessionClient
153
-    :members:
154
-
155
-.. autoclass:: deckhand.client.client.Client
156
-    :members:
157
-
158
-Manager Reference
159
------------------
160
-
161
-For more information about how to use the client managers, refer to the
162
-following 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:
150
+`client module <../contributor/api/deckhand.client.html>`_.

+ 3
- 92
doc/source/operators/exceptions.rst View File

@@ -17,95 +17,6 @@
17 17
 Deckhand Exceptions
18 18
 ===================
19 19
 
20
-.. autoexception:: deckhand.errors.BarbicanClientException
21
-   :members:
22
-   :show-inheritance:
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:
20
+For a list of Deckhand exceptions as well as debugging information related to
21
+each please reference
22
+`Deckhand's errors module <../contributor/api/deckhand.errors.html>`_.

+ 0
- 7
doc/source/users/validation.rst View File

@@ -189,13 +189,6 @@ For post-rendering validation, 2 types of behavior are possible:
189 189
 #. Failure to validate post-rendered documents results in a 500 Internal Server
190 190
    Error getting raised.
191 191
 
192
-Validation Module
193
------------------
194
-
195
-.. autoclass:: deckhand.engine.document_validation.DocumentValidation
196
-   :members:
197
-   :private-members:
198
-
199 192
 .. _schemas:
200 193
 
201 194
 Validation Schemas

+ 2
- 2
tools/build-docs.sh View File

@@ -11,6 +11,6 @@ python -m plantuml doc/source/diagrams/*.uml
11 11
 mv doc/source/diagrams/*.png doc/source/images
12 12
 
13 13
 # Generate documentation.
14
-rm -rf doc/build
15
-rm -rf releasenotes/build
14
+rm -rf doc/build doc/source/contributor/api/ releasenotes/build
15
+sphinx-apidoc -o doc/api deckhand
16 16
 sphinx-build -W -b html doc/source doc/build/html

Loading…
Cancel
Save