PDF documentation build

The is one of community goals that each project could produce a
single PDF file. The pdf should be in the output of openstack-tox-docs
job.

The list of changes:
- add a new pdf-docs environment to enable PDF build,
- sphinxcontrib-svg2pdfconverter is used to handle SVG properly,
- poke versions for sphinx and openstackdocstheme,
- disable usage of xindy for tex,
- do not generate empty pages,
- only build html for toctree and other content-less for pdf sections,
- adjust README to firstly contain "About tripleo" then team & repo tags
  for the better view in PDF-generated contents.
- move the Contributing chapter closer to the beginning for the better
  view in the long list of generated contents.

More about the goal:
https://governance.openstack.org/tc/goals/train/pdf-doc-generation.html
https://etherpad.openstack.org/p/train-pdf-support-goal
https://etherpad.openstack.org/p/pdf-goal-train-common-problems

TeX and  few more packages may be needed to build PDF locally
(listed for bindep):

inkscape [doc platform:dpkg]
fonts-liberation [doc platform:dpkg]
texlive-latex-base [doc platform:dpkg]
texlive-latex-extra [doc platform:dpkg]
texlive-xetex [doc platform:dpkg]
texlive-fonts-recommended [doc platform:dpkg]
xindy [doc platform:dpkg]
latexmk [doc platform:dpkg]
texlive [doc platform:rpm]
texlive-fncychap [doc platform:rpm]
texlive-titlesec [doc platform:rpm]
texlive-tabulary [doc platform:rpm]
texlive-framed [doc platform:rpm]
texlive-wrapfig [doc platform:rpm]
texlive-upquote [doc platform:rpm]
texlive-capt-of [doc platform:rpm]
texlive-needspace [doc platform:rpm]
texlive-polyglossia [doc platform:rpm]
latexmk [doc platform:rpm]
python3-sphinxcontrib-svg2pdfconverter-common [doc platform:rpm]
librsvg2-tools [doc platform:rpm]
librsvg2-bin [doc platform:dpkg]

Change-Id: Ib3bb34191582f581c28f2f8a0281cf3ae44003e8
Signed-off-by: Bogdan Dobrelya <bdobreli@redhat.com>

CONTRIBUTING.rst

@@ -1,17 +1,12 @@
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in the "If you're a developer, start here"
-section of this page:
+section of `How To Contribute Guide <https://wiki.openstack.org/wiki/How_To_Contribute>`_.
-
-   https://wiki.openstack.org/wiki/How_To_Contribute
 
 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
-the workflow documented at:
+the documented `Development Workflow <https://docs.openstack.org/infra/manual/developers.html>`_.
-
-   https://docs.openstack.org/infra/manual/developers.html
 
 Pull requests submitted through GitHub will be ignored.
 
-Bugs should be filed on Launchpad, not GitHub:
+Bugs should be filed on `TripleO at Launchpad <https://bugs.launchpad.net/tripleo>`_
-
+not GitHub.
-   https://bugs.launchpad.net/tripleo

README.rst

@@ -1,15 +1,9 @@
-========================
+===================
-Team and repository tags
+About tripleoclient
-========================
+===================
 
-.. image:: https://governance.openstack.org/tc/badges/python-tripleoclient.svg
+General information
-    :target: https://governance.openstack.org/tc/reference/tags/index.html
+-------------------
-
-.. Change things from this point on
-
-=============
-tripleoclient
-=============
 
 **tripleoclient** is an OpenStackClient (OSC) plugin implementation that
 implements commands useful for TripleO and the install and management of
@@ -21,3 +15,9 @@ for details on using tripleoclient.
 
 See the
 `Release Notes <https://docs.openstack.org/releasenotes/python-tripleoclient>`_
+
+Team and repository tags
+------------------------
+
+.. image:: https://governance.openstack.org/tc/badges/python-tripleoclient.svg
+    :target: https://governance.openstack.org/tc/reference/tags/index.html

doc/requirements.txt

@@ -1,7 +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.
-sphinx>=1.6.2,!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7'  # BSD
+sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
-sphinx>=1.6.2,!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4'  # BSD
+sphinx>=1.8.0,!=2.1.0;python_version>='3.4'  # BSD
-openstackdocstheme>=1.20.0 # Apache-2.0
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+openstackdocstheme>=1.30.0 # Apache-2.0
 reno>=2.5.0 # Apache-2.0

doc/source/conf.py

@@ -23,8 +23,12 @@ extensions = [
     'sphinx.ext.autodoc',
     'openstackdocstheme',
     'cliff.sphinxext',
+    'sphinxcontrib.rsvgconverter',
 ]
 
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
@@ -66,13 +70,13 @@ htmlhelp_basename = 'tripleoclientdoc'
 # [howto/manual]).
 latex_documents = [
     ('index',
-     'tripleoclient.tex',
+     'doc-python-tripleoclient.tex',
-     u'tripleoclient Documentation',
+     u'Tripleoclient Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
 
 # Allow deeper levels of nesting for \begin...\end stanzas
-latex_elements = {'maxlistdepth': 10}
+latex_elements = {'maxlistdepth': 10, 'extraclassoptions': ',openany,oneside'}
 
 # openstackdocstheme options
 repository_name = 'openstack/python-tripleoclient'

doc/source/index.rst

@@ -1,22 +1,20 @@
 =============
-tripleoclient
+Tripleoclient
 =============
 
-tripleoclient is an OpenStackClient plugin.
-
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
    readme
+   contributing
    installation
    usage
    commands
-   contributing
 
-Indices and tables
+.. only:: html
-==================
 
-* :ref:`genindex`
+  Indices and tables
-* :ref:`search`
+  ==================
+
+  * :ref:`genindex`
+  * :ref:`search`

tox.ini

@@ -72,6 +72,17 @@ show-source = True
 builtins = _
 exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,releasenotes
 
+[testenv:pdf-docs]
+basepython = python3
+whitelist_externals = make
+description =
+  Build PDF documentation.
+envdir = {toxworkdir}/docs
+deps = {[testenv:docs]deps}
+commands =
+  sphinx-build -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:genconfig]
 basepython = python3
 setenv =