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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
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
