[openstack-dev] Following the new PTI for document build, broken local builds
sean.mcginnis at gmx.com
Thu Mar 22 13:37:12 UTC 2018
> > 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 . 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.
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. ;)
More information about the OpenStack-dev