From f313d7a87fbc43f2789d3fe46f6e44998ff189d8 Mon Sep 17 00:00:00 2001 From: Bogdan Dobrelya Date: Fri, 16 Aug 2019 00:52:14 +0900 Subject: [PATCH] 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 --- README.rst | 2 +- doc/requirements.txt | 8 +++++++ doc/source/ci/stages-overview.rst | 17 ++++++++++++-- doc/source/conf.py | 17 ++++++++++++++ doc/source/index.rst | 18 +++++++++++++++ .../install/introduction/architecture.rst | 8 ++++--- .../install/introduction/components.rst | 8 ++++--- requirements.txt | 2 +- test-requirements.txt | 4 +--- tox.ini | 22 ++++++++++++++----- 10 files changed, 88 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index cb3e5863..34779d11 100644 --- a/README.rst +++ b/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 diff --git a/doc/requirements.txt b/doc/requirements.txt index 19de1fe6..e50daada 100644 --- a/doc/requirements.txt +++ b/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 diff --git a/doc/source/ci/stages-overview.rst b/doc/source/ci/stages-overview.rst index 1891d74d..d3386574 100644 --- a/doc/source/ci/stages-overview.rst +++ b/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 `_. -.. mermaid:: promotions.mmd + +.. only:: latex + + .. parsed-literal:: + + master --**build-packages**--> + current-consistent -->-- `tripleo-ci promotion `_ --> + current-tripleo -->-- `rdo phase1 promotion `_ --> + current-tripleo-rdo -->-- `rdo phase2 promotion `_ --> + current-tripleo-rdo-internal + +.. only:: html + + .. mermaid:: promotions.mmd *Overview of the tags used during the tripleo promotions stages* diff --git a/doc/source/conf.py b/doc/source/conf.py index 7655ba3e..0f793637 100644 --- a/doc/source/conf.py +++ b/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() diff --git a/doc/source/index.rst b/doc/source/index.rst index 66c97cd6..347b74fe 100644 --- a/doc/source/index.rst +++ b/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 ---------------- diff --git a/doc/source/install/introduction/architecture.rst b/doc/source/install/introduction/architecture.rst index ba95c3ad..4783679d 100644 --- a/doc/source/install/introduction/architecture.rst +++ b/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 diff --git a/doc/source/install/introduction/components.rst b/doc/source/install/introduction/components.rst index a2efe802..99359a1e 100644 --- a/doc/source/install/introduction/components.rst +++ b/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 diff --git a/requirements.txt b/requirements.txt index b2113829..82774cee 100644 --- a/requirements.txt +++ b/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 diff --git a/test-requirements.txt b/test-requirements.txt index 51d68162..34ce2997 100644 --- a/test-requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index 0460b58a..2735b976 100644 --- a/tox.ini +++ b/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