[openstack-dev] Following the new PTI for document build, broken local builds
mordred at inaugust.com
Fri Mar 23 13:03:22 UTC 2018
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.
>>> 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 . 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.
>  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
>>> * 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 . I aim to post instructions on the latter shortly.
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev