On Fri, 2018-03-23 at 12:23 -0400, Doug Hellmann wrote: > Excerpts from Monty Taylor's message of 2018-03-23 08:03:22 -0500: > > On 03/22/2018 05:43 AM, Stephen Finucane wrote: > > > > > > 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. > > > > I'd suggest a #4: > > > > Take the sphinx.ext.apidoc extension and make it a standalone extension > > people can add to doc/requirements.txt and conf.py. That way we don't > > have to convince the sphinx folks to land it. > > > > I'd been thinking for a while "we should just write a sphinx extension > > with the pbr logic in it" - but hadn't gotten around to doing anything > > about it. If you've already written that extension - I think we're in > > potentially great shape! > > That also has the benefit that we don't have to wait for a new sphinx > release to start using it.
I can do this. Where will it live? pbr? openstackdocstheme? Somewhere else? Stephen __________________________________________________________________________ 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