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:
- copy the docs testenvs' dependencies from
  Ib3bb34191582f581c28f2f8a0281cf3ae44003e8
- do not place unrelated to the docs testenvs entries for the
  test-requieremets.txt, add missing flake8
- add the missing sphinxcontrib-mermaid docs requirements
- render mermaid diagrams only for html builds, for PDF use a hand-made
  quick and dirty approximation instead (if used for PDF builds, it
  fails on the py3 deprecated warn() methos)
- add the project architecture and components into the main ToC, omit
  rendering additional contents pages for PDF builds
- add a new pdf-docs environment to enable PDF build,
- sphinxcontrib-svg2pdfconverter is used to handle SVG properly,
- Add requirements for sphinx and poke it for openstackdocstheme,
- disable usage of xindy for tex,
- do not generate empty pages,

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>

README.rst

@@ -44,7 +44,7 @@ repository.
 
 ::
 
-    tox -edocs
+    tox -edocs,pdf-docs,deploy-guide
 
 Now you have the documentation generated for the various available
 formats from the local source. The resulting documentation will be

doc/requirements.txt

@@ -1,2 +1,10 @@
+# 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.8.0,<2.0.0;python_version=='2.7' # BSD
+sphinx>=1.8.0,!=2.1.0;python_version>='3.4'  # BSD
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD
+sphinxcontrib-mermaid>=0.3.1 # BSD
 requests
 pyquery

doc/source/ci/stages-overview.rst

@@ -4,12 +4,25 @@ Promotion Stages
 The list below shows each stage within the RDO promotion workflow.
 Each stage shows the inputs taken and the artifacts produced.
 
-.. note:: All the links shown in the diagram refer to the Master release.
+.. note:: All of the shown links refer to the Master release.
 
           Links for stable branches would include the stable release name,
           for example, `Pike stable release <https://trunk.rdoproject.org/centos7-pike/tripleo-ci-testing/>`_.
 
-.. mermaid:: promotions.mmd
+
+.. only:: latex
+
+  .. parsed-literal::
+
+     master --**build-packages**-->
+     current-consistent -->-- `tripleo-ci promotion <http://cistatus.tripleo.org/promotion/>`_ -->
+     current-tripleo -->-- `rdo phase1 promotion <http://cistatus.tripleo.org/phase1/>`_ -->
+     current-tripleo-rdo -->-- `rdo phase2 promotion <http://cistatus.tripleo.org/phase2/>`_ -->
+     current-tripleo-rdo-internal
+
+.. only:: html
+
+  .. mermaid:: promotions.mmd
 
 *Overview of the tags used during the tripleo promotions stages*
 

doc/source/conf.py

@@ -33,8 +33,12 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinxcontrib.mermaid',
     'openstackdocstheme',
+    'sphinxcontrib.rsvgconverter',
 ]
 
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -138,6 +142,19 @@ def get_latest_version_name():
     return _get_name_version()
 
 
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index',
+     'doc-tripleo-docs.tex',
+     u'TripleO Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# Allow deeper levels of nesting for \begin...\end stanzas
+latex_elements = {'maxlistdepth': 10, 'extraclassoptions': 'openany,oneside'}
+
 oldest_version_name = get_oldest_version_name()
 oldest_version_name_lower = oldest_version_name.lower()
 before_oldest_version_name = get_before_oldest_version_name()

doc/source/index.rst

@@ -16,6 +16,24 @@ Contributor Guide
   contributor/index
   developer/index
 
+|project| Architecture
+----------------------
+
+.. toctree::
+  :maxdepth: 3
+  :includehidden:
+
+  install/introduction/architecture.rst
+
+|project| Components
+----------------------
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  install/introduction/components.rst
+
 Tripleo CI Guide
 ----------------
 

doc/source/install/introduction/architecture.rst

@@ -5,9 +5,11 @@ This document lists the main components of |project|, and gives some
 description of how each component is used. There are links to additional sources
 of information throughout the document.
 
-.. contents::
+.. only:: html
-   :depth: 3
+
-   :backlinks: none
+  .. contents::
+     :depth: 3
+     :backlinks: none
 
 
 Architecture Overview

doc/source/install/introduction/components.rst

@@ -1,9 +1,11 @@
 |project| Components
 ======================
 
-.. contents::
+.. only:: html
-   :depth: 2
+
-   :backlinks: none
+  .. contents::
+     :depth: 2
+     :backlinks: none
 
 This section contains a list of components that |project| uses. The components
 are organized in categories, and include a basic description, useful links, and

requirements.txt

@@ -2,4 +2,4 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-openstackdocstheme>=1.20.0  # Apache-2.0
+openstackdocstheme>=1.30.0  # Apache-2.0

test-requirements.txt

@@ -2,9 +2,7 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 # Doc requirements
-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
-sphinxcontrib-mermaid
 
+flake8
 requests
 pyquery

tox.ini

@@ -16,12 +16,28 @@ commands = {posargs}
 
 [testenv:docs]
 basepython = python3
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands =
     sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
 
+[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:pep8]
 basepython = python3
 whitelist_externals = bash
+deps = -r{toxinidir}/test-requirements.txt
 # We fail pretty horribly on bashate right now
 #commands = bash -c "find scripts -type f | xargs bashate -v"
 #           flake8
@@ -33,10 +49,6 @@ exclude = .tox,dist,*.egg,build
 
 [testenv:deploy-guide]
 basepython = python3
-deps =
+deps = {[testenv:docs]deps}
-   -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-   -r{toxinidir}/requirements.txt
-   -r{toxinidir}/test-requirements.txt
-   -r{toxinidir}/doc/requirements.txt
 
 commands = sphinx-build -a -E -W -d deploy-guide/build/doctrees -b html deploy-guide/source deploy-guide/build/html