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

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: bsipocz

sphinx/directives/patches.py

@@ -9,12 +9,11 @@
 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.docutils import SphinxDirective, _normalize_options
 from sphinx.util.nodes import set_source_info
 from sphinx.util.osutil import SEP, relpath
 
@@ -100,7 +99,7 @@ class Code(SphinxDirective):
     def run(self) -> list[Node]:
         self.assert_has_content()
 
-        set_classes(self.options)
+        self.options = _normalize_options(self.options)
         code = '\n'.join(self.content)
         node = nodes.literal_block(
             code,
@@ -215,7 +214,7 @@ class Rubric(SphinxDirective):
     }
 
     def run(self) -> list[nodes.rubric | nodes.system_message]:
-        set_classes(self.options)
+        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

@@ -6,14 +6,13 @@
 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
+from sphinx.util.docutils import ReferenceRole, SphinxRole, _normalize_options
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -584,10 +583,7 @@ def code_role(
     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)
+    options = _normalize_options(options)
     language = options.get('language', '')
     classes = ['code']
     if language:

sphinx/util/docutils.py

@@ -912,3 +912,19 @@ def _get_settings(
             read_config_files=read_config_files,
         )
     return option_parser.get_default_values()  # type: ignore[return-value]
+
+
+if docutils.__version_info__[:2] < (0, 22):
+    from docutils.parsers.rst.roles import set_classes
+
+    def _normalize_options(options: dict[str, Any] | None) -> dict[str, Any]:
+        if options is None:
+            return {}
+        n_options = options.copy()
+        set_classes(n_options)
+        return n_options
+
+else:
+    from docutils.parsers.rst.roles import (  # type: ignore[attr-defined, no-redef]
+        normalize_options as _normalize_options,  # NoQA: F401
+    )