Open Stack

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