Open Stack

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