Browse Source

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
changes/61/613761/3
Felipe Monteiro 8 months ago
parent
commit
9d91a072cd

+ 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

+ 5
- 0
doc/requirements.txt View File

@@ -5,4 +5,9 @@ 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
 
10
+# NOTE(felipemonteiro): Required by RTD to make oslo.policy and
11
+# oslo.config sample generation work.
12
+oslo.config!=4.3.0,!=4.4.0,>=5.2.0 # Apache-2.0
13
+oslo.policy>=1.33.1 # Apache-2.0

+ 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