Em Fri, 20 Jun 2025 11:22:48 +0900 Akira Yokosawa <akiyks@xxxxxxxxx> escreveu: > Hi Jon, > > On Thu, 19 Jun 2025 15:26:56 -0600, Jonathan Corbet wrote: > > Docutils emits a deprecation warning when the set_class() element method is > > used; that warning disappears into the ether, but it also causes a crash > > with docutils 0.19 when combined with certain versions of Sphinx. > > To be accurate, I'd rather say: > but it also causes a crash > with docutils 0.19 when combined with any version of Sphinx whose > requirement accepts it. > > > > > Avoid the deprecated function and just append directly to the "classes" > > attribute like the documentation says instead. > > Nice! This is the kind of fix I wish I could have come up with by myself. > > Tested OK against debian:12's Sphinx 5.3.0, as well as Sphinx 3.4.3 of > debian:11 and almalinux:9, Sphinx 4.2.0 of Ubuntu 22.04 and other recent > distro Sphinx packages. > > > > > Reported-by: Akira Yokosawa <akiyks@xxxxxxxxx> > > Closes: https://lore.kernel.org/de7bae91-3200-481f-9db2-c0dc382c91dd@xxxxxxxxx/ > > > Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") > > Signed-off-by: Jonathan Corbet <corbet@xxxxxxx> > > Tested-by: Akira Yokosawa <akiyks@xxxxxxxxx> I didn't test it yet, but yesterday I wrote a script which allows us to test for Sphinx version breakages on multiple versions in one go. Using it (and again before this patch, but after my parser-yaml series), I noticed that 6.0.1 with "-jauto" with those packages: alabaster==0.7.13 babel==2.17.0 certifi==2025.6.15 charset-normalizer==3.4.2 docutils==0.18.1 idna==3.10 imagesize==1.4.1 importlib_metadata==8.7.0 Jinja2==3.1.2 MarkupSafe==2.0.0 packaging==25.0 Pygments==2.19.1 PyYAML==5.3.1 requests==2.32.4 snowballstemmer==3.0.1 Sphinx==6.0.1 sphinxcontrib-applehelp==1.0.4 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 urllib3==2.4.0 zipp==3.23.0 is crashing. It sounds to me that the issue is internal to Sphinx, as it runs well with -j1. One possible solution would be to modify: Documentation/sphinx/parallel-wrapper.sh To force "-j1" if Sphinx version is 6.0.1 (and probably 6.0). --- Jon, If you prefer, Maybe you could run the test script before, to check if no regressions happened with other versions. I'll prepare a new version of my patch series today placing the check script at the beginning. Regards, Mauro > > > --- > > TODO for the future: figure out where the warning is going > > > > Documentation/sphinx/automarkup.py | 2 +- > > 1 file changed, 1 insertion(+), 1 deletion(-) > > > > diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py > > index e67eb8e19c22..563033f764bb 100644 > > --- a/Documentation/sphinx/automarkup.py > > +++ b/Documentation/sphinx/automarkup.py > > @@ -240,7 +240,7 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): > > # mark it as a broken xref > > # > > if contnode: > > - contnode.set_class("broken_xref") > > + contnode['classes'].append("broken_xref") Just in case, I would change it to: if 'classes' in countnode: contnode['classes'].append("broken_xref") just to avoid eventual surprises. Regards, Mauro
