[openstack-dev] Following the new PTI for document build, broken local builds

Stephen Finucane sfinucan at redhat.com
Thu Mar 22 10:43:45 UTC 2018

On Wed, 2018-03-21 at 09:57 -0500, Sean McGinnis wrote:
> 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.

That's unfortunate. What we really need is a migration path from the
'pbr' way of doing things to something else. I see three possible
avenues at this point in time:

   1. Start using 'sphinx.ext.autosummary'. Apparently this can do similar
      things to 'sphinx-apidoc' but it takes the form of an extension.
      From my brief experiments, the output generated from this is
      radically different and far less comprehensive than what 'sphinx-
      apidoc' generates. However, it supports templating so we could
      probably configure this somehow and add our own special directive
      somewhere like 'openstackdocstheme'
   2. Push for the 'sphinx.ext.apidoc' extension I proposed some time back
      against upstream Sphinx [1]. This essentially does what the PBR
      extension does but moves configuration into 'conf.py'. However, this
      is currently held up as I can't adequately explain the differences
      between this and 'sphinx.ext.autosummary' (there's definite overlap
      but I don't understand 'autosummary' well enough to compare them).
   3. Modify the upstream jobs that detect the pbr integration and have
      them run 'sphinx-apidoc' before 'sphinx-build'. This is the least
      technically appealing approach as it still leaves us unable to build
      stuff locally and adds yet more "magic" to the gate, but it does let
      us progress.

Try as I may, I don't really have the bandwidth to work on this for
another few weeks so I'd appreciate help from anyone with sufficient
Sphinx-fu to come up with a long-term solution to this issue.


[1] https://github.com/sphinx-doc/sphinx/pull/4101/files

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

More information about the OpenStack-dev mailing list