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 [1]. 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 build_sphinx' 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 (mostly oslo). As noted by Monty in a prior openstack-dev post [2], 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 [3]. To ensure this continued working, the zuul jobs definitions [4] 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 issues. * 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 [5]. 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). Cheers, Stephen [1] https://review.openstack.org/#/q/topic:updated-pti+(status:open+OR+status:merged) [2] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html [3] https://docs.openstack.org/pbr/latest/user/using.html#pbr-setup-cfg [4] https://github.com/openstack-infra/zuul-jobs/blob/d75f5d2b/roles/sphinx/tasks/main.yaml [5] http://www.sphinx-doc.org/en/stable/ext/autosummary.html __________________________________________________________________________ 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