Create tox environment to build pdf documentation

This patch enables building .pdf documentation using new 'pdf-docs'
tox environment. The newly created tox environment creates latex
source codes using sphinx-build and then builds the pdf
documentation using make.

Also, this patch makes minor changes in the documentation source
code to make sure that the .pdf and .html documentation looks
good.

Story: 2006070
Task: 35454

Change-Id: I74a151163812a3dc8fde9f85739882a54ad11fd3

Author: lpiwowar

doc/source/conf.py

@@ -54,6 +54,7 @@
 openstackdocs_repo_name = 'openstack-dev/bashate'
 openstackdocs_bug_project = 'bashate'
 openstackdocs_bug_tag = ''
+openstackdocs_pdf_link = True
 
 # Grouping the document tree for man pages.
 # List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
@@ -80,10 +81,14 @@
 # [howto/manual]).
 latex_documents = [
     ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
+     'doc-%s.tex' % project,
+     u'Bashate Documentation',
      u'Bashate Authors', 'manual'),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+latex_use_xindy = False
+latex_elements = {
+    'extraclassoptions': 'openany,oneside',
+}

doc/source/contributor/index.rst

@@ -1,4 +1,8 @@
 ============
 Contributing
 ============
-.. include:: ./contributing.rst
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing.rst

doc/source/index.rst

@@ -2,8 +2,6 @@
 Welcome to bashate's documentation!
 ===================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 

doc/source/user/index.rst

@@ -2,9 +2,6 @@
 Using bashate
 =============
 
-
-Contents:
-
 .. toctree::
    :maxdepth: 2
 

tox.ini

@@ -22,6 +22,14 @@ commands = flake8
 deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -W -E -b html doc/source doc/build/html
 
+[testenv:pdf-docs]
+deps = {[testenv:docs]deps}
+whitelist_externals =
+   make
+commands =
+   sphinx-build -W -b latex doc/source doc/build/pdf
+   make -C doc/build/pdf
+
 [testenv:venv]
 commands = {posargs}