Open Stack

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