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>
This commit is contained in:
Bogdan Dobrelya 2019-08-16 00:52:14 +09:00
parent 73191f8705
commit f313d7a87f
10 changed files with 88 additions and 18 deletions

View File

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

View File

@ -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 requests
pyquery pyquery

View File

@ -4,12 +4,25 @@ Promotion Stages
The list below shows each stage within the RDO promotion workflow. The list below shows each stage within the RDO promotion workflow.
Each stage shows the inputs taken and the artifacts produced. 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, Links for stable branches would include the stable release name,
for example, `Pike stable release <https://trunk.rdoproject.org/centos7-pike/tripleo-ci-testing/>`_. 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* *Overview of the tags used during the tripleo promotions stages*

View File

@ -33,8 +33,12 @@ extensions = [
'sphinx.ext.intersphinx', 'sphinx.ext.intersphinx',
'sphinxcontrib.mermaid', 'sphinxcontrib.mermaid',
'openstackdocstheme', '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. # The suffix of source filenames.
source_suffix = '.rst' source_suffix = '.rst'
@ -138,6 +142,19 @@ def get_latest_version_name():
return _get_name_version() 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 = get_oldest_version_name()
oldest_version_name_lower = oldest_version_name.lower() oldest_version_name_lower = oldest_version_name.lower()
before_oldest_version_name = get_before_oldest_version_name() before_oldest_version_name = get_before_oldest_version_name()

View File

@ -16,6 +16,24 @@ Contributor Guide
contributor/index contributor/index
developer/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 Tripleo CI Guide
---------------- ----------------

View File

@ -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 description of how each component is used. There are links to additional sources
of information throughout the document. of information throughout the document.
.. contents:: .. only:: html
:depth: 3
:backlinks: none .. contents::
:depth: 3
:backlinks: none
Architecture Overview Architecture Overview

View File

@ -1,9 +1,11 @@
|project| Components |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 This section contains a list of components that |project| uses. The components
are organized in categories, and include a basic description, useful links, and are organized in categories, and include a basic description, useful links, and

View File

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

View File

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

22
tox.ini
View File

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