[openstack-dev] Following the new PTI for document build, broken local builds
dtantsur at redhat.com
Fri Mar 23 10:33:32 UTC 2018
On 03/22/2018 04:39 PM, Sean McGinnis 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 . 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.
> 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.
This is also an issue for clients. I would kindly ask people doing this work to
stop proposing patches that just remove the API reference without any replacement.
> 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:
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev