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

[Akira Yokosawa <akiyks@gmail.com>]

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>

> ---
> 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")
>      return contnode
>  
>  #