From b1713e62557da5d8b52c67a8efe34b2e2bcfc5da Mon Sep 17 00:00:00 2001
From: Thomas Bechtold <tbechtold@suse.com>
Date: Tue, 27 Aug 2019 14:23:45 +0200
Subject: [PATCH] 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                                  | 11 ++++++++++-
 .../shared-file-systems/samples/manila.conf.rst     | 11 +++++++++--
 .../shared-file-systems/samples/policy.rst          | 13 ++++++++++---
 doc/source/contributor/index.rst                    | 10 ++++++----
 doc/source/index.rst                                | 10 ++++++----
 tox.ini                                             |  9 +++++++++
 6 files changed, 50 insertions(+), 14 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 99792ca9aa..06a99b452b 100644
--- a/doc/source/conf.py
+++ b/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,
+}
diff --git a/doc/source/configuration/shared-file-systems/samples/manila.conf.rst b/doc/source/configuration/shared-file-systems/samples/manila.conf.rst
index 24f8bf2600..ac97c1ba4a 100644
--- a/doc/source/configuration/shared-file-systems/samples/manila.conf.rst
+++ b/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.
diff --git a/doc/source/configuration/shared-file-systems/samples/policy.rst b/doc/source/configuration/shared-file-systems/samples/policy.rst
index 03aa339f6c..f41a381d98 100644
--- a/doc/source/configuration/shared-file-systems/samples/policy.rst
+++ b/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.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 0d1578d117..bd15b45b6c 100644
--- a/doc/source/contributor/index.rst
+++ b/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`
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 57804b4161..121a20b503 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -139,10 +139,12 @@ Contents:
 
    reference/index
 
-Additional reference
-~~~~~~~~~~~~~~~~~~~~
+.. only:: html
 
-Contents:
+   Additional reference
+   ~~~~~~~~~~~~~~~~~~~~
 
-* :ref:`genindex`
+   Contents:
+
+   * :ref:`genindex`
 
diff --git a/tox.ini b/tox.ini
index b9c11c8c70..1a1426621f 100644
--- a/tox.ini
+++ b/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