Add PDF documentation build

Add a new tox target to build PDF documentation in accord
with the community goal [0] to have PDF docs available.

Also, only show genindex and search for HTML.  These elements
do not make sense within PDF documents.

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

Change-Id: Ia75423d1efbec65730130eedf169c458b92b0c9f

README.rst

@@ -1,3 +1,11 @@
+Team and repository tags
+------------------------
+
+.. image:: https://governance.openstack.org/tc/badges/manila-ui.svg
+    :target: https://governance.openstack.org/tc/reference/tags/index.html
+
+.. Change things from this point on
+
 =======================================
 manila-ui - Manila Management Dashboard
 =======================================
@@ -7,9 +15,3 @@ manila-ui - Manila Management Dashboard
 * Release notes: https://docs.openstack.org/releasenotes/manila-ui/
 * Source: https://opendev.org/openstack/manila-ui
 * Bugs: https://bugs.launchpad.net/manila-ui
-
-Team and repository tags
-------------------------
-
-.. image:: https://governance.openstack.org/tc/badges/manila-ui.svg
-    :target: https://governance.openstack.org/tc/reference/tags/index.html

bindep.txt

@@ -4,3 +4,11 @@ xvfb [selenium platform:dpkg]
 # already part of xorg-x11-server on openSUSE
 xorg-x11-server-Xvfb [selenium platform:redhat]
 
+# Dependency for pdf document generation
+latexmk
+texlive-xetex
+texlive-fonts-recommended
+fonts-liberation
+inkscape
+librsvg2-bin
+imagemagick

doc/requirements.txt

@@ -0,0 +1,13 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+openstackdocstheme>=1.20.0 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+doc8>=0.6.0 # Apache-2.0
+sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7'  # BSD
+sphinx!=1.6.6,!=1.6.7,!=2.1.0,>=1.6.2;python_version>='3.4'  # BSD
+mock>=2.0.0 # BSD
+os-api-ref>=1.4.0 # Apache-2.0
+ddt>=1.0.1 # MIT
+fixtures>=3.0.0 # Apache-2.0/BSD
+oslotest>=3.2.0 # Apache-2.0

doc/source/conf.py

@@ -26,6 +26,7 @@ extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
     'openstackdocstheme',
+    'sphinx.ext.imgconverter',
 ]
 
 # openstackdocstheme options
@@ -70,15 +71,49 @@ html_theme_path = [openstackdocstheme.get_html_theme_path()]
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
+# Example configuration for intersphinx: refer to the Python standard library.
+#intersphinx_mapping = {'http://docs.python.org/': None}
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
+     'doc-%s.tex' % project,
      u'%s Documentation' % project,
      u'OpenStack Foundation', 'manual'),
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# 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/index.rst

@@ -19,8 +19,10 @@ Contents
    admin/index
    contributor/index
 
-Indices and tables
-------------------
+.. only:: html
 
-* :ref:`genindex`
-* :ref:`search`
+   Indices and tables
+   ------------------
+
+   * :ref:`genindex`
+   * :ref:`search`

tox.ini

@@ -80,6 +80,20 @@ commands =
   rm -rf doc/build
   python setup.py build_sphinx
 
+[testenv:pdf-docs]
+usedevelop = True
+basepython = python3
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
+
+whitelist_externals =
+  make
+commands =
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:releasenotes]
 basepython = python3
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees \