[openstack-dev] Following the new PTI for document build, broken local builds
sfinucan at redhat.com
Wed Mar 21 10:49:02 UTC 2018
tl;dr: Make sure you stop using pbr's autodoc feature before converting
them to the new PTI for docs.
There have been a lot of patches converting projects to use the new
Project Testing Interface for building docs . Generally, these make
the following changes:
1. Move any requirements for building docs or release notes from 'test-
requirements.txt' to 'doc/requirements.txt'
2. Modify 'tox.ini' to call 'sphinx-build' instead of 'python setup.py
Once done, the idea is that the gate will be able to start building
docs by calling the 'sphinx-build' executable directly instead of using
the 'build_sphinx' setuptools command. Unfortunately, this doesn't
always do what you think and has resulted in a few now-broken projects
As noted by Monty in a prior openstack-dev post , some projects rely
on a pbr extension to the 'build_sphinx' setuptools command which can
automatically run the 'sphinx-apidoc' tool before building docs. This
is enabled by configuring some settings in the '[pbr]' section of the
'setup.cfg' file . To ensure this continued working, the zuul jobs
definitions  check for the presence of these settings and build docs
using the legacy 'build_sphinx' command if found. **At no point do the
jobs call the tox job**. As a result, if you convert a project to use
'sphinx-build' in 'tox.ini' without resolving the autodoc issues, you
lose the ability to build docs locally.
I've gone through and proposed a couple of reverts to fix projects
we've already broken. However, going forward, there are two things
people should do to prevent issues like this popping up.
* Firstly, you should remove the '[build_sphinx]' and '[pbr]' sections
from 'setup.cfg' in any patches that aim to convert a project to use
the new PTI. This will ensure the gate catches any potential
* In addition, if your project uses the pbr autodoc feature, you
should either (a) remove these docs from your documentation tree or
(b) migrate to something else like the 'sphinx.ext.autosummary'
extension . I aim to post instructions on the latter shortly.
If anyone has any questions on the above, feel free to reply here or
contact me on IRC (stephenfin).
More information about the OpenStack-dev