Open Stack

Excerpts from Michel Peterson's message of 2018-09-13 10:04:27 +0300:
> On Thu, Sep 13, 2018 at 1:09 AM, Doug Hellmann <doug at doughellmann.com>
> wrote:
> 
> > 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.
> >
> 
> Just a question out of curiosity. You mention that we still want to use the
> docs environment because it allows fine grained control over how the
> documentation is created. However, as I understand, the PDF output will
> happen in a more standardized way and outside of that fine grained control,
> right? That couldn't lead to differences in both documentations? Do we have
> to even worry about that?

Good question.  The idea is to run "tox -e docs" to get the regular
HTML, then something like

   .tox/docs/bin/sphinx-build -b latex doc/build doc/build/latex
   cd doc/build/latex
   make
   cp doc/build/latex/*.pdf doc/build/html

We would run the HTML translation builds in a similar way by invoking
sphinx-build from the virtualenv repeatedly with different locale
settings based on what translations exist.

In my earlier comment, I was thinking of the case where a team runs
a script to generate rst content files before invoking sphinx to
build the HTML. That script would have been run before the PDF
generation happens, so the content should be the same. That also
applies for anyone using sphinx add-ons, which will be available
to the latex builder because we'll be using the version of sphinx
installed in the virtualenv managed by tox.

Doug