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.

Also, due to the opposing graphic format, the .gif file
had to be converted (not renamed) to .png so the LaTeX
builder would accept and read the images.

Change-Id: I6384e56222991d39f4fd1bc99e82be6c89fb16a3
Story: 2006072

bindep.txt

@@ -15,3 +15,7 @@ pki-kra [platform:rpm]
 #Required for cryptography lib
 libssl-dev [platform:dpkg]
 openssl-devel [platform:rpm]
+
+# libsrvg2 is needed for sphinxcontrib-svg2pdfconverter in docs builds.
+librsvg2-tools [doc platform:rpm]
+librsvg2-bin [doc platform:dpkg]

doc/requirements.txt

@@ -1,7 +1,8 @@
 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-httpdomain>=1.3.0 # BSD
 sphinxcontrib-blockdiag>=1.5.4 # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
 reno>=2.5.0 # Apache-2.0
 os-api-ref>=1.4.0 # Apache-2.0
 openstackdocstheme>=1.18.1 # Apache-2.0

doc/source/conf.py

@@ -27,6 +27,7 @@ extensions = [
     'oslo_config.sphinxconfiggen',
     'oslo_policy.sphinxext',
     'oslo_policy.sphinxpolicygen',
+    'sphinxcontrib.rsvgconverter',
 ]
 
 config_generator_config_file = [
@@ -89,10 +90,12 @@ htmlhelp_basename = '%sdoc' % project
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
+     'doc-barbican.tex',
      u'%s Documentation' % project,
      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}

doc/source/contributor/architecture.rst

@@ -12,7 +12,7 @@ Overall Architecture
 
 The next figure presents an overall logical diagram for Barbican.
 
-.. image:: ./../images/barbican-overall-architecture.gif
+.. image:: ./../images/barbican-overall-architecture.png
 
 The API node(s) handle incoming REST requests to Barbican. These nodes can
 interact with the database directly if the request can be completed
@@ -35,7 +35,7 @@ logging.
 
 The next figure examines the components within Barbican.
 
-.. image:: ./../images/barbican-components.gif
+.. image:: ./../images/barbican-components.png
 
 Several potential clients of the Barbican REST interface are noted, including
 `Castellan <https://github.com/openstack/castellan>`_ which presents a generic

doc/source/index.rst

@@ -23,7 +23,7 @@ API.
    configuration/index
    contributor/index
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    api/index.rst
 
@@ -31,7 +31,7 @@ Sample Files
 ============
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    sample_config
    sample_policy

lower-constraints.txt

@@ -114,6 +114,7 @@ six==1.10.0
 smmap2==2.0.3
 snowballstemmer==1.2.1
 Sphinx==1.6.2
+sphinxcontrib-svg2pdfconverter==0.1.0
 sphinxcontrib-websupport==1.0.1
 sqlalchemy-migrate==0.11.0
 SQLAlchemy==1.0.10

tox.ini

@@ -83,10 +83,19 @@ description = Build main documentation
 basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt
 commands=
-    rm -rf doc/build
+    rm -rf doc/build doc/build/doctrees
     sphinx-build -W -b html doc/source doc/build/html
 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:api-guide]
 basepython = python3
 # This environment is called from CI scripts to test and publish
@@ -174,4 +183,3 @@ deps =
   -c{toxinidir}/lower-constraints.txt
   -r{toxinidir}/test-requirements.txt
   -r{toxinidir}/requirements.txt
-