Browse Source

Merge "Generate PDF documentation"

tags/16.0.0.0rc1
Zuul 1 month ago
parent
commit
5fca3f7978

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

@@ -208,23 +208,26 @@ htmlhelp_basename = 'keystonedoc'
208 208
 
209 209
 # -- Options for LaTeX output -------------------------------------------------
210 210
 
211
-latex_elements = {
212
-    # The paper size ('letterpaper' or 'a4paper').
213
-    # 'papersize': 'letterpaper',
211
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
212
+latex_use_xindy = False
214 213
 
215
-    # The font size ('10pt', '11pt' or '12pt').
216
-    # 'pointsize': '10pt',
214
+latex_domain_indices = False
217 215
 
218
-    # Additional stuff for the LaTeX preamble.
219
-    # 'preamble': '',
216
+latex_elements = {
217
+    'makeindex': '',
218
+    'printindex': '',
219
+    'preamble': r'\setcounter{tocdepth}{3}',
220
+    'maxlistdepth': 10,
220 221
 }
221 222
 
222 223
 # Grouping the document tree into LaTeX files. List of tuples (source
223 224
 # start file, target name, title, author, documentclass
224 225
 # [howto/manual]).
226
+# NOTE(gyee): Specify toctree_only=True for a better document structure of
227
+# the generated PDF file.
225 228
 latex_documents = [
226
-    ('index', 'keystone.tex', u'Keystone Documentation',
227
-     u'OpenStack', 'manual'),
229
+    ('index', 'doc-keystone.tex', u'Keystone Documentation',
230
+     u'OpenStack', 'manual', True)
228 231
 ]
229 232
 
230 233
 # The name of an image file (relative to this directory) to place at the top of

+ 5
- 2
doc/source/configuration/config-options.rst View File

@@ -8,8 +8,11 @@ Configuration
8 8
 The Identity service is configured in the ``/etc/keystone/keystone.conf`` file.
9 9
 
10 10
 The following tables provide a comprehensive list of the Identity
11
-service options. For a sample configuration file, refer to
12
-:doc:`samples/keystone-conf`.
11
+service options.
12
+
13
+.. only:: html
14
+
15
+   For a sample configuration file, refer to :doc:`samples/keystone-conf`.
13 16
 
14 17
 .. show-options::
15 18
    :config-file: config-generator/keystone.conf

+ 14
- 4
doc/source/configuration/index.rst View File

@@ -8,8 +8,18 @@ This section provides a list of all possible options and
8 8
 sample files for keystone configuration.
9 9
 
10 10
 .. toctree::
11
-    :maxdepth: 2
11
+   :maxdepth: 2
12 12
 
13
-    config-options.rst
14
-    policy.rst
15
-    samples/index.rst
13
+   config-options.rst
14
+   policy.rst
15
+
16
+.. # NOTE(gyee): Sample files are only available in HTML document.
17
+   # Inline sample files with literalinclude hit LaTeX processing error
18
+   # like TeX capacity exceeded and direct links are discouraged in PDF doc.
19
+
20
+.. only:: html
21
+
22
+   .. toctree::
23
+      :maxdepth: 2
24
+
25
+      samples/index.rst

+ 5
- 2
doc/source/configuration/policy.rst View File

@@ -5,8 +5,11 @@ Policy configuration
5 5
 Configuration
6 6
 ~~~~~~~~~~~~~
7 7
 
8
-The following is an overview of all available policies in Keystone. For a sample
9
-configuration file, refer to :doc:`samples/policy-yaml`.
8
+The following is an overview of all available policies in Keystone.
9
+
10
+.. only:: html
11
+
12
+   For a sample configuration file, refer to :doc:`samples/policy-yaml`.
10 13
 
11 14
 .. show-policy::
12 15
    :config-file: ../../config-generator/keystone-policy-generator.conf

+ 20
- 0
tox.ini View File

@@ -142,6 +142,26 @@ commands=
142 142
     bash -c "rm -rf doc/source/api"
143 143
     sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
144 144
 
145
+# FIXME(gyee): we need to pre-create the doc/build/pdf/_static directory as a
146
+# workaround because sphinx_feature_classification.support_matrix extension
147
+# is operating under the assumption that the _static directory already exist
148
+# and trying to copy support-matrix.css into it. We need to remove
149
+# the workaround after this patch has merged:
150
+# https://review.opendev.org/#/c/679860
151
+[testenv:pdf-docs]
152
+basepython = python3
153
+envdir = {toxworkdir}/docs
154
+deps = {[testenv:docs]deps}
155
+whitelist_externals =
156
+  make
157
+  mkdir
158
+  rm
159
+commands =
160
+  rm -rf doc/build/pdf
161
+  mkdir -p doc/build/pdf/_static
162
+  sphinx-build -W -b latex doc/source doc/build/pdf
163
+  make -C doc/build/pdf
164
+
145 165
 [testenv:releasenotes]
146 166
 basepython = python3
147 167
 deps = -r{toxinidir}/doc/requirements.txt

Loading…
Cancel
Save