Open Stack

> > 
> > 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.
> > 
> > Try as I may, I don't really have the bandwidth to work on this for
> > another few weeks so I'd appreciate help from anyone with sufficient
> > Sphinx-fu to come up with a long-term solution to this issue.
> > 
> > Cheers,
> > Stephen
> > 
> 
> I think we could probably go with 1 until and if 2 becomes an option. It does
> change output quite a bit.
> 
> I played around with 3, but I think we will have enough differences between
> projects as to _where_ specifically this generated content needs to be placed
> that it will make that approach a little more brittle.
> 

One other things that comes to mind - I think most service projects, if they
are even using this, could probably just drop it. I've found the generated
"API" documentation for service modules to be of very limited use.

That would at least narrow things down to lib projects. So this would still be
an issue for the oslo libs for sure. In that case, you do what that module API
documentation in most cases.

But personally, I would encourage service projects to get around this issue by
just not doing it. It would appear that would take care of a large chunk of the
current usage:

http://codesearch.openstack.org/?q=autodoc_index_modules&i=nope&files=setup.cfg&repos=