PDF Documentation Build tox target

This patch adds a `pdf-docs` tox target that will build
PDF versions of our docs. As per the Train community goal:

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

Add sphinxcontrib-svg2pdfconverter to doc/requirements.txt
to convert our SVGs.

Update docs requirement as well to follow PTI.

Change-Id: I0b866b2e57557290533ee7e7e162e56c9c17cf54
Story: 2006072

doc/requirements.txt

@@ -2,5 +2,6 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 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,>=1.6.2;python_version>='3.4'  # BSD
+sphinx>=1.8.0,!=2.1.0;python_version>='3.4'  # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
 openstackdocstheme>=1.20.0 # Apache-2.0

doc/source/conf.py

@@ -23,6 +23,7 @@ extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
     'openstackdocstheme',
+    'sphinxcontrib.rsvgconverter',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -67,11 +68,13 @@ htmlhelp_basename = 'python-barbicanclientdoc'
 # [howto/manual]).
 latex_documents = [
     ('index',
-     'python-barbicanclient.tex',
+     'doc-python-barbicanclient.tex',
      u'python-barbicanclient Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
 
+latex_use_xindy = False
+
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
 

lower-constraints.txt

@@ -64,6 +64,7 @@ requestsexceptions==1.2.0
 rfc3986==0.3.1
 simplejson==3.5.1
 six==1.10.0
+sphinxcontrib-svg2pdfconverter==0.1.0
 stevedore==1.20.0
 stestr==2.0.0
 testtools==2.2.0

test-requirements.txt

@@ -12,3 +12,4 @@ oslotest>=3.2.0 # Apache-2.0
 nose>=1.3.7 # LGPL
 oslo.config>=5.2.0 # Apache-2.0
 python-openstackclient>=3.12.0 # Apache-2.0
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

tox.ini

@@ -37,12 +37,26 @@ basepython = python3
 commands = {posargs}
 
 [testenv:docs]
+# This environment is called from CI scripts to test and publish
+# the main docs to https://docs.openstack.org/python-barbicanclient
+description = Build main documentation
 basepython = python3
-deps =
-       -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-       -r{toxinidir}/requirements.txt
-       -r{toxinidir}/doc/requirements.txt
-commands = sphinx-build -b html -W doc/source doc/build/html
+deps = -r{toxinidir}/doc/requirements.txt
+commands=
+    rm -rf doc/build/html doc/build/doctrees
+    sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
+whitelist_externals = rm
+
+[testenv:pdf-docs]
+basepython = python3
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  make
+  rm
+commands =
+  rm -rf doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
 
 [testenv:functional]
 # This tox env is purely to make local test development easier