There have been a couple of threads about an updated "PTI" for
documentation bouncing around the mailing list of late.
I've been told the reasoning behind this change and what is required
has not been made clear so here goes my attempt at explaining it. In
short, there are two problems we're trying to work around with this
* The legacy 'build_sphinx' setuptools command provided by pbr has
been found to be lacking. It's buggy as hell, frequently breaks with
Sphinx version bumps, and is generally a PITA to maintain. We (the
oslo team) want to remove this feature to ease our maintenance
* The recent move to zuul v3 has changed how documentation is built in
the gate. Previously, zuul called the 'docs' target in tox (e.g.
'tox -e docs'), which would run whatever the project team had
defined for that target. With zuul v3, zuul no longer calls this.
Instead, it call either 'python setup.py build_sphinx' or 'sphinx-
build' (more on this below). This means everything you wish to do as
part of the documentation build must now be done via Sphinx
Both the oslo and infra teams have a strong incentive to drop support
for the 'build_sphinx' command (albeit for different reasons) but doing
so isn't simply a case of calling 'sphinx-build' instead. In order to
migrate, some steps are required:
1. pbr's 'build_sphinx' setuptools command provides some additional
functionality on top of 'sphinx-build'. This must be replaced by
2. Calls to 'python setup.py build_sphinx' must be replaced by
additional calls to 'sphinx-build'
3. Documentation requirements must be moved to 'doc/requirements.txt'
to avoid having to install every requirement of a project simply to
The first of these has already be achieved: 'openstackdocstheme'
recently gained support for automatically configuring the project name
and version in generated documentation , which replaced that aspect
of the 'build_sphinx' command. Similarly, the 'sphinxcontrib-apidoc'
Sphinx extension  was produced in order to provide a way to
automatically generate API documentation as part of 'sphinx-build'
rather than by having to make a secondary call to 'sphinx-apidoc'
(which the gate, which, once again, no longer runs anything but
'sphinx-build' or 'python setup.py build_sphinx', would not do).
The second step is the troublesome bit and has been the reason for most
of the individual patches to various projects. The steps necessary to
make this change have been documented multiple times on the list but
they're listed here once again for posterity:
* If necessary, enable 'sphinxcontrib.apidoc' as described at .
* Make sure you're using 'openstackdocstheme', assuming your project
is an official OpenStack one.
* Remove the 'build_sphinx' section from 'setup.cfg' (this is
described at  but applies whether you need that or not).
* Update your doc/releasenotes/api-guide targets in 'tox.ini' so
you're using the same commands as the gate.
The third change should be self-explanatory and infra have reasons for
requesting it. It's generally easiest to do this as part of the above.
Hopefully this clears things up for people. If anyone has any
questions, feel free to reach out to me on IRC (stephenfin) and I'll be
happy to help.
PS: For those that curious, the decision on whether to run 'python
setup.py build_sphinx' command or 'sphinx-build' in the gate is based
on the presence of a 'build_sphinx' section in 'setup.cfg'. If present,
the former is run. If not, we use 'sphinx-build'. This is why it's
necessary to remove that section from 'setup.cfg'.
OpenStack Development Mailing List (not for usage questions)