Add pdf documentation build in tox

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.

- Inline sample config file is skipped for PDF doc
  to avoid an LaTeX error "TeX capacity exceeded".
- Download link of sample config and policy files are disabled
  for PDF doc as relative links do not make sense.
- "Search" and "genindex" page is only enabled for HTML doc
  as they work only for HTML doc.

Co-Authored-By: Akihiro Motoki <amotoki@gmail.com>
Change-Id: Ib8ce96f4d043dcf0cfe6d3f8b64879f07bc5958c

doc/source/conf.py

@@ -227,7 +227,7 @@ htmlhelp_basename = 'cinderdoc'
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ('index', 'Cinder.tex', u'Cinder Documentation',
+    ('index', 'cinder.tex', u'Cinder Documentation',
      u'Cinder Contributors', 'manual'),
 ]
 
@@ -247,3 +247,15 @@ latex_documents = [
 
 # If false, no module index is generated.
 # latex_use_modindex = True
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+latex_domain_indices = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+    'maxlistdepth': 10,
+}

doc/source/configuration/block-storage/samples/cinder.conf.rst

@@ -6,8 +6,15 @@ The ``cinder.conf`` file is installed in ``/etc/cinder`` by default.
 When you manually install the Block Storage service, the options in the
 ``cinder.conf`` file are set to default values.
 
-The sample configuration file can also be viewed in
-`file form <../../../_static/cinder.conf.sample>`_.
+.. only:: html
 
-.. literalinclude:: ../../../_static/cinder.conf.sample
-   :language: ini
+   The sample configuration file can also be viewed in
+   `file form <../../../_static/cinder.conf.sample>`_.
+
+   .. literalinclude:: ../../../_static/cinder.conf.sample
+      :language: ini
+
+.. only:: latex
+
+   See the on-line version of this documentation for the full example
+   config file.

doc/source/configuration/block-storage/samples/policy.yaml.rst

@@ -31,7 +31,9 @@ The following provides a listing of the default policies. It is not recommended
 to copy this file into ``/etc/cinder`` unless you are planning on providing a
 different policy for an operation that is not the default.
 
-The sample policy file can also be viewed in `file form
-<../../../_static/cinder.policy.yaml.sample>`_.
+.. only:: html
+
+   The sample policy file can also be viewed in `file form
+   <../../../_static/cinder.policy.yaml.sample>`_.
 
 .. literalinclude:: ../../../_static/cinder.policy.yaml.sample

doc/source/contributor/index.rst

@@ -82,10 +82,12 @@ Other Resources
 
    Module Reference <api/modules>
 
-Indices and tables
-------------------
+.. only:: html
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Indices and tables
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`
 

doc/source/index.rst

@@ -152,10 +152,13 @@ Contents:
 
    common/glossary.rst
 
-Indices and tables
-~~~~~~~~~~~~~~~~~~
 
-Contents:
+.. only:: html
 
-* :ref:`genindex`
-* :ref:`search`
+   Indices and tables
+   ~~~~~~~~~~~~~~~~~~
+
+   Contents:
+
+   * :ref:`genindex`
+   * :ref:`search`

tox.ini

@@ -136,10 +136,23 @@ deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/doc/requirements.txt
 commands =
-  rm -fr doc/build doc/source/contributor/api/ .autogenerated
+  rm -fr doc/source/contributor/api/
+  rm -fr doc/build/html doc/build/doctrees
   sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
 whitelist_externals = rm
 
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+commands =
+  rm -fr doc/source/contributor/api/
+  rm -fr doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+whitelist_externals =
+  make
+  rm
+
 [testenv:gendriverlist]
 basepython = python3
 sitepackages = False