[openstack-dev] [doc][i18n][infra][tc] plan for PDF and translation builds for documentation

Matthew Treinish mtreinish at kortar.org
Thu Sep 13 20:09:42 UTC 2018

On Thu, Sep 13, 2018 at 07:23:53AM -0600, Doug Hellmann wrote:
> 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

To be fair, I've looked at this several times in the past, and sphinx's latex
generation is good enough for the simple case, but on more complex documents
it doesn't really work too well. For example, on nova I added this a while ago:


To work around some issues with this workflow. It was enough to get the
generated latex to actually compile back then. But, that script has bitrotted
and needs to be updated, because the latex from sphinx for nova's docs no
longer compiles. (also I submitted a patch to sphinx in the meantime to
fix the check mark latex output) I'm afraid that it'll be a constant game
of cat and mouse trying to get everything to build.

I think that we'll find that on most projects' documentation we will need
to massage the latex output from sphinx to build pdfs.

-Matt Treinish

> 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180913/0d2f0154/attachment.sig>

More information about the OpenStack-dev mailing list