Merge "Add pdf documentation build in tox"

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
+.. only:: html
-`file form <../../../_static/cinder.conf.sample>`_.
 
-.. literalinclude:: ../../../_static/cinder.conf.sample
+   The sample configuration file can also be viewed in
-   :language: ini
+   `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
+.. only:: html
-<../../../_static/cinder.policy.yaml.sample>`_.
+
+   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`
+   Indices and tables
-* :ref:`modindex`
+   ------------------
-* :ref:`search`
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`
 

doc/source/index.rst

@@ -161,10 +161,13 @@ Contents:
 
    common/glossary.rst
 
-Indices and tables
-~~~~~~~~~~~~~~~~~~
 
-Contents:
+.. only:: html
 
-* :ref:`genindex`
+   Indices and tables
-* :ref:`search`
+   ~~~~~~~~~~~~~~~~~~
+
+   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