Open Stack

> > 
> > Unfortunately this will not work to just revert the changes. That may fix
> > things locally, but they will not pass in gate by going back to the old way.
> > 
> > Any cases of this will have to actually be updated to not use the unsupported
> > pieces you point out. But the doc builds will still need to be done the way
> > they are now, as that is what the PTI requires at this point.
> 
> 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.

All that said, I think once we decide on a path and get something out there,
there does seem to be a group of folks that are more than willing to follow
that established pattern and desseminate it out to all other projects. We just
need to decide I guess.

Your sphinx-fu is probably stronger than mine, so hopefully someone else with
more experience can chime in here. ;)

Sean