[openstack-dev] Following the new PTI for document build, broken local builds

Dmitry Tantsur 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 [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.

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:
> http://codesearch.openstack.org/?q=autodoc_index_modules&i=nope&files=setup.cfg&repos=
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

More information about the OpenStack-dev mailing list