[openstack-dev] Following the new PTI for document build, broken local builds
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 . 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