Use normalize_options() from Docutils in preference to set_classes()

sphinx/directives/patches.py

@@ -1,23 +1,28 @@
 from __future__ import annotations
 
 import os
 from pathlib import Path
+from packaging.version import Version
 from typing import TYPE_CHECKING, cast
 
-from docutils import nodes
+from docutils import nodes, __version__
 from docutils.nodes import make_id
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives import images, tables
 from docutils.parsers.rst.directives.misc import Meta
-from docutils.parsers.rst.roles import set_classes
 
 from sphinx.directives import optional_int
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import set_source_info
 from sphinx.util.osutil import SEP, relpath
 
+if Version(__version__) < Version('0.22'):
+    from docutils.parsers.rst.roles import normalized_role_options as normalize_options
+else:
+    from docutils.parsers.rst.roles import normalize_options
+
 if TYPE_CHECKING:
     from typing import ClassVar
 
@@ -100,7 +105,7 @@
     def run(self) -> list[Node]:
         self.assert_has_content()
 
-        set_classes(self.options)
+        normalize_options(self.options)
         code = '\n'.join(self.content)
         node = nodes.literal_block(
             code,
@@ -215,7 +220,7 @@
     }
 
     def run(self) -> list[nodes.rubric | nodes.system_message]:
-        set_classes(self.options)
+        normalize_options(self.options)
         rubric_text = self.arguments[0]
         textnodes, messages = self.parse_inline(rubric_text, lineno=self.lineno)
         if 'heading-level' in self.options:

sphinx/roles.py

@@ -1,19 +1,20 @@
 """Handlers for additional ReST roles."""
 
 from __future__ import annotations
 
 import re
+from packaging.version import Version
 from typing import TYPE_CHECKING
 
 import docutils.parsers.rst.directives
 import docutils.parsers.rst.roles
 import docutils.parsers.rst.states
 from docutils import nodes, utils
 
 from sphinx import addnodes
 from sphinx.locale import _, __
 from sphinx.util import ws_re
 from sphinx.util.docutils import ReferenceRole, SphinxRole
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -584,10 +585,14 @@
     options: dict[str, Any] | None = None,
     content: Sequence[str] = (),
 ) -> tuple[list[Node], list[system_message]]:
+
     if options is None:
         options = {}
     options = options.copy()
-    docutils.parsers.rst.roles.set_classes(options)
+    if Version(docutils.__version__) < Version('0.22'):
+        docutils.parsers.rst.roles.set_classes(options)
+    else:
+        docutils.parsers.rst.roles.normalize_options(options)
     language = options.get('language', '')
     classes = ['code']
     if language: