Open Stack

On Wed, 2018-03-28 at 14:14 -0500, Sean McGinnis wrote:
> 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?
> 

Nope - sphinx-apidoc and the likes use autodoc under the hood. You can
see this by checking the output in 'contributor/api' or the likes.

Stephen

> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev