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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev