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
parent
73191f8705
commit
f313d7a87f
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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*
|
||||
|
||||
|
||||
@ -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()
|
||||
|
||||
@ -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
|
||||
----------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,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
|
||||
|
||||
@ -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
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…
Reference in New Issue
Block a user