Open Stack

On Wed, Mar 21, 2018 at 10:49:02AM +0000, Stephen Finucane wrote:
> tl;dr: Make sure you stop using pbr's autodoc feature before converting
> them to the new PTI for docs.
> 
> [snip]
> 
> 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.
> 

Unfortunately this will not work to just revert the changes. That may fix
things locally, but they will not pass in gate by going back to the old way.

Any cases of this will have to actually be updated to not use the unsupported
pieces you point out. But the doc builds will still need to be done the way
they are now, as that is what the PTI requires at this point.

>  * 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.
>