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

Sean McGinnis sean.mcginnis at gmx.com
Wed Mar 28 19:14:44 UTC 2018

On Thu, Mar 22, 2018 at 10:43:45AM +0000, Stephen Finucane wrote:
> 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]
> > > 
> 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.

It's not mentioned here, but I discovered today that Cinder is using the
sphinx.ext.autodoc module. Is there any issue with using this?

More information about the OpenStack-dev mailing list