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