Generate PDF documentation

This patch adds a new tox job/command for building the pdf
version of documentation.

tox -epdf-docs

In addition to adjusting the infra requirement for PDF build
support, the following changes are made to build a PDF doc

- Download link of config_options, sample config and policy
  files are disabled for PDF doc as relative links do not
  make sense.
- Pre-create the doc/build/pdf/_static directory as a
  workaround because sphinx_feature_classification.support_matrix extension
  is operating under the assumption that the _static directory already exist
  and trying to copy support-matrix.css into it. We need to remove
  this workaround once the problem in the support_matrix extension is fixed.
- Use the toctree_only=True workaround to avoid TOC duplicate links.

Change-Id: Ief8df5f6a5a22b8d0530458ac45f344a72cc3e49

doc/source/conf.py

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

doc/source/configuration/config-options.rst

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

doc/source/configuration/index.rst

@@ -8,8 +8,18 @@ This section provides a list of all possible options and
 sample files for keystone configuration.
 
 .. toctree::
-    :maxdepth: 2
+   :maxdepth: 2
 
-    config-options.rst
+   config-options.rst
-    policy.rst
+   policy.rst
-    samples/index.rst
+
+.. # NOTE(gyee): Sample files are only available in HTML document.
+   # Inline sample files with literalinclude hit LaTeX processing error
+   # like TeX capacity exceeded and direct links are discouraged in PDF doc.
+
+.. only:: html
+
+   .. toctree::
+      :maxdepth: 2
+
+      samples/index.rst

doc/source/configuration/policy.rst

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

tox.ini

@@ -142,6 +142,26 @@ commands=
     bash -c "rm -rf doc/source/api"
     sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
 
+# FIXME(gyee): we need to pre-create the doc/build/pdf/_static directory as a
+# workaround because sphinx_feature_classification.support_matrix extension
+# is operating under the assumption that the _static directory already exist
+# and trying to copy support-matrix.css into it. We need to remove
+# the workaround after this patch has merged:
+# https://review.opendev.org/#/c/679860
+[testenv:pdf-docs]
+basepython = python3
+envdir = {toxworkdir}/docs
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+  mkdir
+  rm
+commands =
+  rm -rf doc/build/pdf
+  mkdir -p doc/build/pdf/_static
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:releasenotes]
 basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt