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: I8190e0a4f169e1a3268f5e724c30a1c809739dd6

doc/source/conf.py

@@ -184,23 +184,26 @@ htmlhelp_basename = '%sdoc' % project
 
 # -- 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').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+    'maxlistdepth': 10,
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
+# NOTE(jacky06): Specify toctree_only=True for a better document structure of
+# the generated PDF file.
 latex_documents = [
-  ('index', 'kolla-cli.tex', u'kolla-cli Documentation',
-   u'Oracle', 'manual'),
+  ('index', 'doc-kolla-cli.tex', u'kolla-cli Documentation',
+   u'Oracle', 'manual', True),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

tox.ini

@@ -98,6 +98,19 @@ commands =
   rm -rf doc/build
   sphinx-build -W -b html doc/source doc/build/html
 
+[testenv:pdf-docs]
+basepython = python3
+whitelist_externals =
+  make
+  mkdir
+  rm
+deps = {[testenv:docs]deps}
+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
 whitelist_externals = rm