[all] Failure to build (FTBFS) with Sphinx 5.0 and docutils 0.18

Michael Johnson johnsomor at gmail.com
Fri Jun 24 16:14:18 UTC 2022

I took a quick look at os-api-ref. The tests are failing with docutils 0.18.

They have changed how column widths are defined for tables and the
tests have static HTML assertions that are failing[1].

>From the docutils release notes[2] I found that there is now a
table-style directive "colwidths-grid" that in theory would restore
the colgroup output[3].

[1] https://opendev.org/openstack/os-api-ref/src/branch/master/os_api_ref/tests/test_microversions.py#L60
[2] https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26
[3] https://docutils.sourceforge.io/docs/user/config.html#toc-entry-82

The challenge I have is I'm not very familiar with docutils, so I'm
not really sure how to apply that style setting.
Maybe this will provide enough hints someone more familiar with
docutils can quickly fix this.


On Fri, Jun 24, 2022 at 7:28 AM Jeremy Stanley <fungi at yuggoth.org> wrote:
> On 2022-06-24 14:56:59 +0200 (+0200), Thomas Goirand wrote:
> [...]
> > I'd appreciate a bit of help from the OpenStack project here, to fix these
> > before Sphinx 5 and Docutils 0.18 are uploaded to Debian Unstable.
> >
> > If you do have a fix, a quick link in these bug reports would be lovely.
> Yes, it looks like https://review.opendev.org/846848 (autoproposed)
> is attempting to update our constraints for Sphinx from 4.5.0 to
> 5.0.2 (though keeping docutils 0.17.1 at the moment, presumably due
> to a transitive version cap somewhere in the dependency set) and is
> failing its cross-osc-tox-docs canary build with the following:
>     Warning, treated as error: extlinks: Sphinx-6.0 will require a
>     caption string to contain exactly one '%s' and all other '%'
>     need to be escaped as '%%'.
> Unfortunately that's not an easy condition to scan our entire
> codebase for (captions with more or fewer than one '%s' in them), so
> it's hard to know how widespread the problem is.
> Looking at the bug you linked for the nova package build, it seems
> like that's a got unit a test failure unrelated to Sphinx or
> docutils. Are you sure it's related?
> For the os-api-ref bug, that seems to be an API response mismatch in
> its tests. I can't say for sure without looking deeper that the
> tests don't use Sphinx or docutils to generate the HTML involved,
> but it's not clear to me that's the cause at least.
> The openstacksdk bug similarly appears to be for a unit test
> failure, something to do with tempfile handling I think, not
> documentation building.
> The cloudkitty bug does look like a problem with the documentation
> source being incompatible with Sphinx involving the wsmeext
> extension, so different than we're seeing on the requirements tests
> at least.
> The dogpile.cache and repoze.who bugs also look Sphinx-related,
> though the OpenStack community doesn't develop those projects so
> someone will probably need to reach out to them wherever they
> collaborate officially.
> --
> Jeremy Stanley

More information about the openstack-discuss mailing list