Build pdf docs

This follows the instructions [1] in an attempt to build pdf docs.

Several doc/source/conf.py changes are required to get this to work.
The most important one is

    'maxlistdepth': '10',

which prevents the build process from stalling out and dropping the
caller into an interactive session.

[1] https://etherpad.openstack.org/p/train-pdf-support-goal

Change-Id: Icf7c22bf9d1de6fb2a74a756c370930d4c00b0b9
Story: 2006110
Task: 35398

doc/source/conf.py

@@ -126,9 +126,23 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    ('index', 'Placement.tex', u'Placement Documentation',
+    ('index', 'doc-placement.tex', u'Placement Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
+latex_domain_indices = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+    'maxlistdepth': '10',
+}
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+# Disable smartquotes, they don't work in latex
+smartquotes_excludes = {'builders': ['latex']}
 
 # -- Options for openstackdocstheme -------------------------------------------
 

tox.ini

@@ -117,6 +117,15 @@ commands =
   # Test the redirects
   whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
 
+[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:api-ref]
 description =
   Generate the API ref. Called from CI scripts to test and publish to docs.openstack.org.