On Thu, 2018-04-05 at 16:36 -0400, Zane Bitter wrote: > 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.
I'd be more in favour of changing the zuul job to build with the '-W' flag. To be honest, there is no good reason to not have this flag enabled. I'm not sure that will be a popular opinion though as it may break some projects' builds (correctly, but still). I'll propose a patch against zuul-jobs and see what happens :) Stephen __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
