From 1f3763636b1193b97664f3d9269a82428d28f19b Mon Sep 17 00:00:00 2001
From: Masayuki Igawa <masayuki@igawa.io>
Date: Wed, 2 Oct 2019 18:48:31 +0900
Subject: [PATCH] Add PDF documentation build

This commit adds PDF documentation build target 'pdf-docs' that will
build PDF versions of our docs. And this commit also updates 'docs'
target to use sphinx-build command as well as 'pdf-docs' target.

This is one of the Train community goals:

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

Change-Id: Iae6bc9ae92fe61385c424923eaad35dc449880e9
Story: #2006070
Task: #35455
---
 doc/requirements.txt |  6 ++++--
 doc/source/conf.py   |  3 ++-
 doc/source/index.rst |  8 +++++++-
 tox.ini              | 11 ++++++++++-
 4 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index d959d44..2194dc4 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,6 +1,8 @@
 # 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.18.1 # Apache-2.0
+openstackdocstheme>=1.20.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+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
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a37cb7c..7d86e7c 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinxcontrib.rsvgconverter',
     'openstackdocstheme'
 ]
 
@@ -73,7 +74,7 @@ htmlhelp_basename = '%sdoc' % project
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
+     'doc-%s.tex' % project,
      u'%s Documentation' % project,
      u'OpenStack Foundation', 'manual'),
 ]
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3253d1d..4f71244 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -26,4 +26,10 @@ if your coverage rate is down.
 Indices and tables
 ==================
 
-* :ref:`search`
+.. only:: html
+
+  * :ref:`Coverage2SQL document search <search>`: Search the contents of this
+    document.
+
+* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider
+  set of OpenStack documentation, including forums.
\ No newline at end of file
diff --git a/tox.ini b/tox.ini
index 22da84b..8f184b1 100644
--- a/tox.ini
+++ b/tox.ini
@@ -45,7 +45,16 @@ deps =
   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
   -r{toxinidir}/requirements.txt
   -r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
+
+[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:debug]
 basepython = python3