On 03/22/2018 05:43 AM, Stephen Finucane wrote:
On Wed, 2018-03-21 at 09:57 -0500, Sean McGinnis wrote:
On Wed, Mar 21, 2018 at 10:49:02AM +0000, Stephen Finucane wrote:
tl;dr: Make sure you stop using pbr's autodoc feature before converting
them to the new PTI for docs.
[snip]
I've gone through and proposed a couple of reverts to fix projects
we've already broken. However, going forward, there are two things
people should do to prevent issues like this popping up.
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.
I'd suggest a #4:
Take the sphinx.ext.apidoc extension and make it a standalone extension
people can add to doc/requirements.txt and conf.py. That way we don't
have to convince the sphinx folks to land it.
I'd been thinking for a while "we should just write a sphinx extension
with the pbr logic in it" - but hadn't gotten around to doing anything
about it. If you've already written that extension - I think we're in
potentially great shape!
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
[1] https://github.com/sphinx-doc/sphinx/pull/4101/files
* Firstly, you should remove the '[build_sphinx]' and '[pbr]' sections
from 'setup.cfg' in any patches that aim to convert a project to use
the new PTI. This will ensure the gate catches any potential
issues.
* In addition, if your project uses the pbr autodoc feature, you
should either (a) remove these docs from your documentation tree or
(b) migrate to something else like the 'sphinx.ext.autosummary'
extension [5]. I aim to post instructions on the latter shortly.
__________________________________________________________________________
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
