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? __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev