Open Stack

Ian has been working for a while on enabling PDF and translation
support for our documentation build job [1][2]. After exploring a
few different approaches, today at the PTG I think we were able to
agree on a plan that will let us move ahead.

The tl;dr version is that we want to add some extra steps to the
existing openstack-tox-docs job (or make a new job that includes
those steps and change the PTI project template so projects start
using it transparently). The changes to the job will be made so
that if the PDF and translation builds work the results will be
published and if they fail that will not trigger a job failure.

The longer version is that we want to continue to use the existing
tox environment in each project as the basis for the job, since
that allows teams to control the version of python used, the
dependencies installed, and add custom steps to their build (such
as for pre-processing the documentation). So, the new or updated
job will start by running "tox -e docs" as it does today. Then it
will run Sphinx again with the instructions to build PDF output,
and copy the results into the directory that the publish job will
use to sync to the web server. And then it will run the scripts to
build translated versions of the documentation as HTML, and copy
the results into place for publishing.

There are a few settings that can/should be configured via the
Sphinx conf.py file, but rather than trying to push updates into
all of the project repos we will look into passing the options on
the command line or making the openstackdocstheme inject those
settings. This would apply to the setting to control the latex
processor as well as fonts or other settings that control the output.
Those things all relate to the format of the output, so it seems
appropriate to have the theme control them.

To cut down on any delays caused by introducing several consecutive
sphinx-build runs to the documentation job we plan to have the check
and gate jobs only run the translation portion of the build if the
message catalog files for a language are modified.

Since this work will all happen inside the documentation build job,
and it will be enabled for all teams automatically, we do not need
to update the Project Testing Interface, and Ian can abandon his
governance changes.

Monty is going to work on the implementation with Ian using
openstacksdk as a test bed [3].

As usual, please let me know if I've left out or mistaken any
details.

Doug

[1] https://review.openstack.org/572559
[2] https://review.openstack.org/588110
[3] https://review.openstack.org/601659