Open Stack

Excerpts from Stephen Finucane's message of 2018-03-23 17:25:42 +0000:
> 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
> 

I think the idea is to make a new thing. If you put it in the
sphinx-contrib org on github it will be easy for other people to
contribute and use it.

Doug