Re: docs: sphinx: avoid using the deprecated node.set_class()

[Mauro Carvalho Chehab <maurochehab@gmail.com>]

Em Fri, 20 Jun 2025 11:22:48 +0900
Akira Yokosawa <akiyks@gmail.com> 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@gmail.com>  
> 
> Closes: https://lore.kernel.org/de7bae91-3200-481f-9db2-c0dc382c91dd@gmail.com/
> 
> > Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too")
> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>  
> 
> Tested-by: Akira Yokosawa <akiyks@gmail.com>

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