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