Open Stack

On 21/03/18 06:49, Stephen Finucane wrote:
> 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.

How can we enable warning_is_error in the gate with the new PTI? It's 
easy enough to add the -W flag in tox.ini for local builds, but as you 
say the tox job is never called in the gate. In the gate zuul checks for 
it in the [build_sphinx] section of setup.cfg:

https://git.openstack.org/cgit/openstack-infra/zuul-jobs/tree/roles/sphinx/library/sphinx_check_warning_is_error.py#n23

So I think it makes more sense to remove the [pbr] section, but leave 
the [build_sphinx] section?

thanks,
Zane.