Browse Source

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>
changes/62/682362/6
Bogdan Dobrelya 2 years ago
parent
commit
f313d7a87f
  1. 2
      README.rst
  2. 8
      doc/requirements.txt
  3. 17
      doc/source/ci/stages-overview.rst
  4. 17
      doc/source/conf.py
  5. 18
      doc/source/index.rst
  6. 8
      doc/source/install/introduction/architecture.rst
  7. 8
      doc/source/install/introduction/components.rst
  8. 2
      requirements.txt
  9. 4
      test-requirements.txt
  10. 22
      tox.ini

2
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

8
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

17
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*

17
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()

18
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
----------------

8
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::
:depth: 3
:backlinks: none
.. only:: html
.. contents::
:depth: 3
:backlinks: none
Architecture Overview

8
doc/source/install/introduction/components.rst

@ -1,9 +1,11 @@
|project| Components
======================
.. contents::
:depth: 2
:backlinks: none
.. only:: html
.. 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

2
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

4
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

22
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 =
-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
deps = {[testenv:docs]deps}
commands = sphinx-build -a -E -W -d deploy-guide/build/doctrees -b html deploy-guide/source deploy-guide/build/html
Loading…
Cancel
Save