Add PDF documentation build

This commit adds a new tox target to build PDF documentation.
It's a community goal[0] to have PDF docs available.

Also some minor fixes are needed for PDF:
- Only show genindex and search for HTML. Theses elements do not make
sense within PDF documents
- Do not include full config sample files. This will not work and
produces a "Dimension too large" error during the latex run.

[0]
https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.html

Change-Id: I66b8c47d599c97e66c2ca76faa66204d5e7c9c3b

doc/source/conf.py

@@ -244,7 +244,7 @@ htmlhelp_basename = 'maniladoc'
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ('index', 'Manila.tex', u'Manila Developer Documentation',
+    ('index', 'manila.tex', u'Manila Developer Documentation',
      u'Manila contributors', 'manual'),
 ]
 
@@ -264,3 +264,12 @@ latex_documents = [
 
 # If false, no module index is generated.
 # latex_use_modindex = True
+
+latex_domain_indices = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+    'maxlistdepth': 10,
+}

doc/source/configuration/shared-file-systems/samples/manila.conf.rst

@@ -9,5 +9,12 @@ in the ``manila.conf`` file are set to default values.
 The ``manila.conf`` file contains most of the options needed to configure
 the Shared File Systems service.
 
-.. literalinclude:: ../../../_static/manila.conf.sample
-   :language: ini
+.. only:: html
+
+   .. literalinclude:: ../../../_static/manila.conf.sample
+      :language: ini
+
+.. only:: latex
+
+   See the online version of this documentation for the full config
+   file example.

doc/source/configuration/shared-file-systems/samples/policy.rst

@@ -5,7 +5,14 @@ Policy configuration
 Configuration
 ~~~~~~~~~~~~~
 
-The following is an overview of all available policies in Manila.
+.. only:: html
 
-.. show-policy::
-   :config-file: etc/manila/manila-policy-generator.conf
+   The following is an overview of all available policies in Manila.
+
+   .. show-policy::
+      :config-file: etc/manila/manila-policy-generator.conf
+
+.. only:: latex
+
+   See the online version of this documentation for the list of available
+   policies in Manila.

doc/source/contributor/index.rst

@@ -88,9 +88,11 @@ Module Reference
    driver_filter_goodness_weigher
    share_migration
 
-Indices and tables
-------------------
+.. only:: html
 
-* :ref:`genindex`
-* :ref:`search`
+   Indices and tables
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`search`
 

doc/source/index.rst

@@ -139,10 +139,12 @@ Contents:
 
    reference/index
 
-Additional reference
-~~~~~~~~~~~~~~~~~~~~
+.. only:: html
 
-Contents:
+   Additional reference
+   ~~~~~~~~~~~~~~~~~~~~
 
-* :ref:`genindex`
+   Contents:
+
+   * :ref:`genindex`
 

tox.ini

@@ -88,6 +88,15 @@ commands =
   doc8 --ignore D001 --ignore-path .tox --ignore-path doc/build --ignore-path manila.egg-info -e .txt -e .rst -e .inc
 whitelist_externals = rm
 
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+commands =
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:bindep]
 # Do not install any requirements. We want this to be fast and work even if
 # system dependencies are missing, since it's used to tell you what system