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