Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/domains/std/__init__.py

@@ -2,17 +2,17 @@
 
 from __future__ import annotations
 
+import operator
 import re
 from copy import copy
-from typing import TYPE_CHECKING, Any, ClassVar, Final, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.nodes import Element, Node, system_message
-from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst import directives
 from docutils.statemachine import StringList
 
 from sphinx import addnodes
-from sphinx.addnodes import desc_signature, pending_xref
+from sphinx.addnodes import pending_xref
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, ObjType
 from sphinx.locale import _, __
@@ -23,8 +23,13 @@ from sphinx.util.nodes import clean_astext, make_id, make_refnode
 from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator, Set
+    from collections.abc import Callable, Iterable, Iterator, MutableSequence, Set
+    from typing import Any, ClassVar, Final
 
+    from docutils.nodes import Element, Node, system_message
+    from docutils.parsers.rst import Directive
+
+    from sphinx.addnodes import desc_signature
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
@@ -46,9 +51,7 @@ samp_role = EmphasizedLiteral()
 
 
 class GenericObject(ObjectDescription[str]):
-    """
-    A generic x-ref directive registered with Sphinx.add_object_type().
-    """
+    """A generic x-ref directive registered with Sphinx.add_object_type()."""
 
     indextemplate: str = ''
     parse_node: Callable[[BuildEnvironment, str, desc_signature], str] | None = None
@@ -63,7 +66,9 @@ class GenericObject(ObjectDescription[str]):
             name = ws_re.sub(' ', sig)
         return name
 
-    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: str, sig: str, signode: desc_signature
+    ) -> None:
         node_id = make_id(self.env, self.state.document, self.objtype, name)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -72,7 +77,7 @@ class GenericObject(ObjectDescription[str]):
             colon = self.indextemplate.find(':')
             if colon != -1:
                 indextype = self.indextemplate[:colon].strip()
-                indexentry = self.indextemplate[colon + 1:].strip() % (name,)
+                indexentry = self.indextemplate[colon + 1 :].strip() % (name,)
             else:
                 indextype = 'single'
                 indexentry = self.indextemplate % (name,)
@@ -87,12 +92,15 @@ class EnvVar(GenericObject):
 
 
 class EnvVarXRefRole(XRefRole):
-    """
-    Cross-referencing role for environment variables (adds an index entry).
-    """
+    """Cross-referencing role for environment variables (adds an index entry)."""
 
-    def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: Element,
-                     is_ref: bool) -> tuple[list[Node], list[system_message]]:
+    def result_nodes(
+        self,
+        document: nodes.document,
+        env: BuildEnvironment,
+        node: Element,
+        is_ref: bool,
+    ) -> tuple[list[Node], list[system_message]]:
         if not is_ref:
             return [node], []
         varname = node['reftarget']
@@ -131,10 +139,12 @@ class ConfigurationValue(ObjectDescription[str]):
     def _toc_entry_name(self, sig_node: desc_signature) -> str:
         if not sig_node.get('_toc_parts'):
             return ''
-        name, = sig_node['_toc_parts']
+        (name,) = sig_node['_toc_parts']
         return name
 
-    def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: str, sig: str, signode: desc_signature
+    ) -> None:
         node_id = make_id(self.env, self.state.document, self.objtype, name)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -179,9 +189,7 @@ class ConfigurationValue(ObjectDescription[str]):
 
 
 class Target(SphinxDirective):
-    """
-    Generic target for user-defined cross-reference types.
-    """
+    """Generic target for user-defined cross-reference types."""
 
     indextemplate = ''
 
@@ -205,7 +213,7 @@ class Target(SphinxDirective):
             colon = indexentry.find(':')
             if colon != -1:
                 indextype = indexentry[:colon].strip()
-                indexentry = indexentry[colon + 1:].strip()
+                indexentry = indexentry[colon + 1 :].strip()
             inode = addnodes.index(entries=[(indextype, indexentry, node_id, '', None)])
             ret.insert(0, inode)
         name = self.name
@@ -219,9 +227,7 @@ class Target(SphinxDirective):
 
 
 class Cmdoption(ObjectDescription[str]):
-    """
-    Description of a command-line option (.. option).
-    """
+    """Description of a command-line option (.. option)."""
 
     def handle_signature(self, sig: str, signode: desc_signature) -> str:
         """Transform an option description into RST nodes."""
@@ -231,10 +237,15 @@ class Cmdoption(ObjectDescription[str]):
             potential_option = potential_option.strip()
             m = option_desc_re.match(potential_option)
             if not m:
-                logger.warning(__('Malformed option description %r, should '
-                                  'look like "opt", "-opt args", "--opt args", '
-                                  '"/opt args" or "+opt args"'), potential_option,
-                               location=signode)
+                logger.warning(
+                    __(
+                        'Malformed option description %r, should '
+                        'look like "opt", "-opt args", "--opt args", '
+                        '"/opt args" or "+opt args"'
+                    ),
+                    potential_option,
+                    location=signode,
+                )
                 continue
             optname, args = m.groups()
             if optname[-1] == '[' and args[-1] == ']':
@@ -243,13 +254,13 @@ class Cmdoption(ObjectDescription[str]):
                 args = '[' + args
 
             if count:
-                if self.env.config.option_emphasise_placeholders:
+                if self.config.option_emphasise_placeholders:
                     signode += addnodes.desc_sig_punctuation(',', ',')
                     signode += addnodes.desc_sig_space()
                 else:
                     signode += addnodes.desc_addname(', ', ', ')
             signode += addnodes.desc_name(optname, optname)
-            if self.env.config.option_emphasise_placeholders:
+            if self.config.option_emphasise_placeholders:
                 add_end_bracket = False
                 if args:
                     if args[0] == '[' and args[-1] == ']':
@@ -281,7 +292,9 @@ class Cmdoption(ObjectDescription[str]):
             raise ValueError
         return firstname
 
-    def add_target_and_index(self, firstname: str, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, firstname: str, sig: str, signode: desc_signature
+    ) -> None:
         currprogram = self.env.ref_context.get('std:program')
         for optname in signode.get('allnames', []):  # type: ignore[var-annotated]
             prefixes = ['cmdoption']
@@ -296,24 +309,29 @@ class Cmdoption(ObjectDescription[str]):
         self.state.document.note_explicit_target(signode)
 
         domain = self.env.domains.standard_domain
-        for optname in signode.get('allnames', []):
-            domain.add_program_option(currprogram, optname,
-                                      self.env.docname, signode['ids'][0])
+        for optname in signode.get('allnames', ()):
+            domain.add_program_option(
+                currprogram, optname, self.env.docname, signode['ids'][0]
+            )
 
         # create an index entry
         if currprogram:
             descr = _('%s command line option') % currprogram
         else:
             descr = _('command line option')
-        for option in signode.get('allnames', []):  # type: ignore[var-annotated]
+        for option in signode.get('allnames', ()):  # type: ignore[var-annotated]
             entry = f'{descr}; {option}'
-            self.indexnode['entries'].append(('pair', entry, signode['ids'][0], '', None))
+            self.indexnode['entries'].append((
+                'pair',
+                entry,
+                signode['ids'][0],
+                '',
+                None,
+            ))
 
 
 class Program(SphinxDirective):
-    """
-    Directive to name the program for which options are documented.
-    """
+    """Directive to name the program for which options are documented."""
 
     has_content = False
     required_arguments = 1
@@ -331,8 +349,14 @@ class Program(SphinxDirective):
 
 
 class OptionXRefRole(XRefRole):
-    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool,
-                     title: str, target: str) -> tuple[str, str]:
+    def process_link(
+        self,
+        env: BuildEnvironment,
+        refnode: Element,
+        has_explicit_title: bool,
+        title: str,
+        target: str,
+    ) -> tuple[str, str]:
         refnode['std:program'] = env.ref_context.get('std:program')
         return title, target
 
@@ -348,9 +372,15 @@ def split_term_classifiers(line: str) -> tuple[str, str | None]:
     return term, first_classifier
 
 
-def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_key: str | None,
-                       source: str, lineno: int, node_id: str | None, document: nodes.document,
-                       ) -> nodes.term:
+def make_glossary_term(
+    env: BuildEnvironment,
+    textnodes: Iterable[Node],
+    index_key: str | None,
+    source: str,
+    lineno: int,
+    node_id: str | None,
+    document: nodes.document,
+) -> nodes.term:
     # get a text-only representation of the term and register it
     # as a cross-reference target
     term = nodes.term('', '', *textnodes)
@@ -378,8 +408,7 @@ def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_k
 
 
 class Glossary(SphinxDirective):
-    """
-    Directive to create a glossary with cross-reference targets for :term:
+    """Directive to create a glossary with cross-reference targets for :term:
     roles.
     """
 
@@ -394,7 +423,7 @@ class Glossary(SphinxDirective):
     def run(self) -> list[Node]:
         node = addnodes.glossary()
         node.document = self.state.document
-        node['sorted'] = ('sorted' in self.options)
+        node['sorted'] = 'sorted' in self.options
 
         # This directive implements a custom format of the reST definition list
         # that allows multiple lines of terms before the definition.  This is
@@ -407,7 +436,9 @@ class Glossary(SphinxDirective):
         in_comment = False
         was_empty = True
         messages: list[Node] = []
-        for line, (source, lineno) in zip(self.content, self.content.items, strict=True):
+        for line, (source, lineno) in zip(
+            self.content, self.content.items, strict=True
+        ):
             # empty line -> add to last definition
             if not line:
                 if in_definition and entries:
@@ -425,23 +456,39 @@ class Glossary(SphinxDirective):
                 # first term of definition
                 if in_definition:
                     if not was_empty:
-                        messages.append(self.state.reporter.warning(
-                            _('glossary term must be preceded by empty line'),
-                            source=source, line=lineno))
+                        messages.append(
+                            self.state.reporter.warning(
+                                _('glossary term must be preceded by empty line'),
+                                source=source,
+                                line=lineno,
+                            )
+                        )
                     entries.append(([(line, source, lineno)], StringList()))
                     in_definition = False
                 # second term and following
                 else:
                     if was_empty:
-                        messages.append(self.state.reporter.warning(
-                            _('glossary terms must not be separated by empty lines'),
-                            source=source, line=lineno))
+                        messages.append(
+                            self.state.reporter.warning(
+                                _(
+                                    'glossary terms must not be separated by empty lines'
+                                ),
+                                source=source,
+                                line=lineno,
+                            )
+                        )
                     if entries:
                         entries[-1][0].append((line, source, lineno))
                     else:
-                        messages.append(self.state.reporter.warning(
-                            _('glossary seems to be misformatted, check indentation'),
-                            source=source, line=lineno))
+                        messages.append(
+                            self.state.reporter.warning(
+                                _(
+                                    'glossary seems to be misformatted, check indentation'
+                                ),
+                                source=source,
+                                line=lineno,
+                            )
+                        )
             elif in_comment:
                 pass
             else:
@@ -452,9 +499,13 @@ class Glossary(SphinxDirective):
                 if entries:
                     entries[-1][1].append(line[indent_len:], source, lineno)
                 else:
-                    messages.append(self.state.reporter.warning(
-                        _('glossary seems to be misformatted, check indentation'),
-                        source=source, line=lineno))
+                    messages.append(
+                        self.state.reporter.warning(
+                            _('glossary seems to be misformatted, check indentation'),
+                            source=source,
+                            line=lineno,
+                        )
+                    )
             was_empty = False
 
         # now, parse all the entries into a big definition list
@@ -469,9 +520,15 @@ class Glossary(SphinxDirective):
                 textnodes, sysmsg = self.parse_inline(term_, lineno=lineno)
 
                 # use first classifier as a index key
-                term = make_glossary_term(self.env, textnodes,
-                                          first_classifier, source, lineno,
-                                          node_id=None, document=self.state.document)
+                term = make_glossary_term(
+                    self.env,
+                    textnodes,
+                    first_classifier,
+                    source,
+                    lineno,
+                    node_id=None,
+                    document=self.state.document,
+                )
                 term.rawsource = line
                 system_messages.extend(sysmsg)
                 termnodes.append(term)
@@ -481,7 +538,10 @@ class Glossary(SphinxDirective):
             if definition:
                 offset = definition.items[0][1]
                 definition_nodes = nested_parse_to_nodes(
-                    self.state, definition, offset=offset, allow_section_headings=False,
+                    self.state,
+                    definition,
+                    offset=offset,
+                    allow_section_headings=False,
                 )
             else:
                 definition_nodes = []
@@ -494,14 +554,14 @@ class Glossary(SphinxDirective):
         return [*messages, node]
 
 
-def token_xrefs(text: str, productionGroup: str = '') -> list[Node]:
-    if len(productionGroup) != 0:
-        productionGroup += ':'
+def token_xrefs(text: str, production_group: str = '') -> Iterable[Node]:
+    if len(production_group) != 0:
+        production_group += ':'
     retnodes: list[Node] = []
     pos = 0
     for m in token_re.finditer(text):
         if m.start() > pos:
-            txt = text[pos:m.start()]
+            txt = text[pos : m.start()]
             retnodes.append(nodes.Text(txt))
         token = m.group(1)
         if ':' in token:
@@ -516,9 +576,10 @@ def token_xrefs(text: str, productionGroup: str = '') -> list[Node]:
                 target = token
         else:
             title = token
-            target = productionGroup + token
-        refnode = pending_xref(title, reftype='token', refdomain='std',
-                               reftarget=target)
+            target = production_group + token
+        refnode = pending_xref(
+            title, reftype='token', refdomain='std', reftarget=target
+        )
         refnode += nodes.literal(token, title, classes=['xref'])
         retnodes.append(refnode)
         pos = m.end()
@@ -528,9 +589,7 @@ def token_xrefs(text: str, productionGroup: str = '') -> list[Node]:
 
 
 class ProductionList(SphinxDirective):
-    """
-    Directive to list grammar productions.
-    """
+    """Directive to list grammar productions."""
 
     has_content = False
     required_arguments = 1
@@ -538,47 +597,117 @@ class ProductionList(SphinxDirective):
     final_argument_whitespace = True
     option_spec: ClassVar[OptionSpec] = {}
 
+    # The backslash handling is from ObjectDescription.get_signatures
+    _nl_escape_re: Final = re.compile(r'\\\n')
+
+    # Get 'name' from triples of rawsource, name, definition (tokens)
+    _name_getter = operator.itemgetter(1)
+
     def run(self) -> list[Node]:
-        domain = self.env.domains.standard_domain
-        node: Element = addnodes.productionlist()
+        name_getter = self._name_getter
+        lines = self._nl_escape_re.sub('', self.arguments[0]).splitlines()
+
+        # Extract production_group argument.
+        # Must be before extracting production definition triples.
+        production_group = self.production_group(lines=lines, options=self.options)
+        production_lines = list(self.production_definitions(lines))
+        max_name_len = max(map(len, map(name_getter, production_lines)))
+        node_location = self.get_location()
+
+        productions = [
+            self.make_production(
+                rawsource=rule,
+                name=name,
+                tokens=tokens,
+                production_group=production_group,
+                max_len=max_name_len,
+                location=node_location,
+            )
+            for rule, name, tokens in production_lines
+        ]
+        node = addnodes.productionlist('', *productions)
         self.set_source_info(node)
-        # The backslash handling is from ObjectDescription.get_signatures
-        nl_escape_re = re.compile(r'\\\n')
-        lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
-
-        productionGroup = ""
-        first_rule_seen = False
-        for rule in lines:
-            if not first_rule_seen and ':' not in rule:
-                productionGroup = rule.strip()
-                continue
-            first_rule_seen = True
-            try:
-                name, tokens = rule.split(':', 1)
-            except ValueError:
-                break
-            subnode = addnodes.production(rule)
-            name = name.strip()
-            subnode['tokenname'] = name
-            if subnode['tokenname']:
-                prefix = 'grammar-token-%s' % productionGroup
-                node_id = make_id(self.env, self.state.document, prefix, name)
-                subnode['ids'].append(node_id)
-                self.state.document.note_implicit_target(subnode, subnode)
-
-                if len(productionGroup) != 0:
-                    objName = f"{productionGroup}:{name}"
-                else:
-                    objName = name
-                domain.note_object('token', objName, node_id, location=node)
-            subnode.extend(token_xrefs(tokens, productionGroup))
-            node.append(subnode)
         return [node]
 
+    @staticmethod
+    def production_group(
+        *,
+        lines: MutableSequence[str],
+        options: dict[str, Any],  # NoQA: ARG004
+    ) -> str:
+        # get production_group
+        if not lines or ':' in lines[0]:
+            return ''
+        production_group = lines[0].strip()
+        lines[:] = lines[1:]
+        return production_group
+
+    @staticmethod
+    def production_definitions(
+        lines: Iterable[str], /
+    ) -> Iterator[tuple[str, str, str]]:
+        """Yield triples of rawsource, name, definition (tokens)."""
+        for line in lines:
+            if ':' not in line:
+                break
+            name, _, tokens = line.partition(':')
+            yield line, name.strip(), tokens.strip()
+
+    def make_production(
+        self,
+        *,
+        rawsource: str,
+        name: str,
+        tokens: str,
+        production_group: str,
+        max_len: int,
+        location: str,
+    ) -> addnodes.production:
+        production_node = addnodes.production(rawsource, tokenname=name)
+        if name:
+            production_node += self.make_name_target(
+                name=name, production_group=production_group, location=location
+            )
+        production_node.append(self.separator_node(name=name, max_len=max_len))
+        production_node += token_xrefs(text=tokens, production_group=production_group)
+        production_node.append(nodes.Text('\n'))
+        return production_node
+
+    def make_name_target(
+        self,
+        *,
+        name: str,
+        production_group: str,
+        location: str,
+    ) -> addnodes.literal_strong:
+        """Make a link target for the given production."""
+        name_node = addnodes.literal_strong(name, name)
+        prefix = f'grammar-token-{production_group}'
+        node_id = make_id(self.env, self.state.document, prefix, name)
+        name_node['ids'].append(node_id)
+        self.state.document.note_implicit_target(name_node, name_node)
+        obj_name = f'{production_group}:{name}' if production_group else name
+        std = self.env.domains.standard_domain
+        std.note_object('token', obj_name, node_id, location=location)
+        return name_node
+
+    @staticmethod
+    def separator_node(*, name: str, max_len: int) -> nodes.Text:
+        """Return seperator between 'name' and 'tokens'."""
+        if name:
+            return nodes.Text(' ::= '.rjust(max_len - len(name) + 5))
+        return nodes.Text(' ' * (max_len + 5))
+
 
 class TokenXRefRole(XRefRole):
-    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool,
-                     title: str, target: str) -> tuple[str, str]:
+    def process_link(
+        self,
+        env: BuildEnvironment,
+        refnode: Element,
+        has_explicit_title: bool,
+        title: str,
+        target: str,
+    ) -> tuple[str, str]:
         target = target.lstrip('~')  # a title-specific thing
         if not self.has_explicit_title and title[0] == '~':
             if ':' in title:
@@ -589,8 +718,7 @@ class TokenXRefRole(XRefRole):
 
 
 class StandardDomain(Domain):
-    """
-    Domain for all objects that don't fit into another domain or are added
+    """Domain for all objects that don't fit into another domain or are added
     via the application interface.
     """
 
@@ -600,8 +728,7 @@ class StandardDomain(Domain):
     object_types: dict[str, ObjType] = {
         'term': ObjType(_('glossary term'), 'term', searchprio=-1),
         'token': ObjType(_('grammar token'), 'token', searchprio=-1),
-        'label': ObjType(_('reference label'), 'ref', 'keyword',
-                         searchprio=-1),
+        'label': ObjType(_('reference label'), 'ref', 'keyword', searchprio=-1),
         'confval': ObjType('configuration value', 'confval'),
         'envvar': ObjType(_('environment variable'), 'envvar'),
         'cmdoption': ObjType(_('program option'), 'option'),
@@ -618,42 +745,42 @@ class StandardDomain(Domain):
         'productionlist': ProductionList,
     }
     roles: dict[str, RoleFunction | XRefRole] = {
-        'option':  OptionXRefRole(warn_dangling=True),
+        'option': OptionXRefRole(warn_dangling=True),
         'confval': XRefRole(warn_dangling=True),
-        'envvar':  EnvVarXRefRole(),
+        'envvar': EnvVarXRefRole(),
         # links to tokens in grammar productions
-        'token':   TokenXRefRole(),
+        'token': TokenXRefRole(),
         # links to terms in glossary
-        'term':    XRefRole(innernodeclass=nodes.inline,
-                            warn_dangling=True),
+        'term': XRefRole(innernodeclass=nodes.inline, warn_dangling=True),
         # links to headings or arbitrary labels
-        'ref':     XRefRole(lowercase=True, innernodeclass=nodes.inline,
-                            warn_dangling=True),
+        'ref': XRefRole(
+            lowercase=True, innernodeclass=nodes.inline, warn_dangling=True
+        ),
         # links to labels of numbered figures, tables and code-blocks
-        'numref':  XRefRole(lowercase=True,
-                            warn_dangling=True),
+        'numref': XRefRole(lowercase=True, warn_dangling=True),
         # links to labels, without a different title
         'keyword': XRefRole(warn_dangling=True),
         # links to documents
-        'doc':     XRefRole(warn_dangling=True, innernodeclass=nodes.inline),
+        'doc': XRefRole(warn_dangling=True, innernodeclass=nodes.inline),
     }
 
     initial_data: Final = {  # type: ignore[misc]
-        'progoptions': {},      # (program, name) -> docname, labelid
-        'objects': {},          # (type, name) -> docname, labelid
-        'labels': {             # labelname -> docname, labelid, sectionname
+        'progoptions': {},  # (program, name) -> docname, labelid
+        'objects': {},  # (type, name) -> docname, labelid
+        'labels': {  # labelname -> docname, labelid, sectionname
             'genindex': ('genindex', '', _('Index')),
             'modindex': ('py-modindex', '', _('Module Index')),
-            'search':   ('search', '', _('Search Page')),
+            'search': ('search', '', _('Search Page')),
         },
-        'anonlabels': {         # labelname -> docname, labelid
+        'anonlabels': {  # labelname -> docname, labelid
             'genindex': ('genindex', ''),
             'modindex': ('py-modindex', ''),
-            'search':   ('search', ''),
+            'search': ('search', ''),
         },
     }
 
-    _virtual_doc_names: dict[str, tuple[str, str]] = {  # labelname -> docname, sectionname
+    # labelname -> docname, sectionname
+    _virtual_doc_names: dict[str, tuple[str, str]] = {
         'genindex': ('genindex', _('Index')),
         'modindex': ('py-modindex', _('Module Index')),
         'search': ('search', _('Search Page')),
@@ -661,7 +788,7 @@ class StandardDomain(Domain):
 
     dangling_warnings = {
         'term': 'term not in glossary: %(target)r',
-        'numref':  'undefined label: %(target)r',
+        'numref': 'undefined label: %(target)r',
         'keyword': 'unknown keyword: %(target)r',
         'doc': 'unknown document: %(target)r',
         'option': 'unknown option: %(target)r',
@@ -678,12 +805,15 @@ class StandardDomain(Domain):
         super().__init__(env)
 
         # set up enumerable nodes
-        self.enumerable_nodes = copy(self.enumerable_nodes)  # create a copy for this instance
-        for node, settings in env.app.registry.enumerable_nodes.items():
+        self.enumerable_nodes = copy(
+            self.enumerable_nodes
+        )  # create a copy for this instance
+        for node, settings in env._registry.enumerable_nodes.items():
             self.enumerable_nodes[node] = settings
 
-    def note_hyperlink_target(self, name: str, docname: str, node_id: str,
-                              title: str = '') -> None:
+    def note_hyperlink_target(
+        self, name: str, docname: str, node_id: str, title: str = ''
+    ) -> None:
         """Add a hyperlink target for cross reference.
 
         .. warning::
@@ -699,8 +829,11 @@ class StandardDomain(Domain):
         .. versionadded:: 3.0
         """
         if name in self.anonlabels and self.anonlabels[name] != (docname, node_id):
-            logger.warning(__('duplicate label %s, other instance in %s'),
-                           name, self.env.doc2path(self.anonlabels[name][0]))
+            logger.warning(
+                __('duplicate label %s, other instance in %s'),
+                name,
+                self.env.doc2path(self.anonlabels[name][0]),
+            )
 
         self.anonlabels[name] = (docname, node_id)
         if title:
@@ -708,18 +841,25 @@ class StandardDomain(Domain):
 
     @property
     def objects(self) -> dict[tuple[str, str], tuple[str, str]]:
-        return self.data.setdefault('objects', {})  # (objtype, name) -> docname, labelid
+        # (objtype, name) -> docname, labelid
+        return self.data.setdefault('objects', {})
 
-    def note_object(self, objtype: str, name: str, labelid: str, location: Any = None,
-                    ) -> None:
+    def note_object(
+        self, objtype: str, name: str, labelid: str, location: Any = None
+    ) -> None:
         """Note a generic object for cross reference.
 
         .. versionadded:: 3.0
         """
         if (objtype, name) in self.objects:
             docname = self.objects[objtype, name][0]
-            logger.warning(__('duplicate %s description of %s, other instance in %s'),
-                           objtype, name, docname, location=location)
+            logger.warning(
+                __('duplicate %s description of %s, other instance in %s'),
+                objtype,
+                name,
+                docname,
+                location=location,
+            )
         self.objects[objtype, name] = (self.env.docname, labelid)
 
     @property
@@ -738,33 +878,42 @@ class StandardDomain(Domain):
 
     @property
     def progoptions(self) -> dict[tuple[str | None, str], tuple[str, str]]:
-        return self.data.setdefault('progoptions', {})  # (program, name) -> docname, labelid
+        return self.data.setdefault(
+            'progoptions', {}
+        )  # (program, name) -> docname, labelid
 
     @property
     def labels(self) -> dict[str, tuple[str, str, str]]:
-        return self.data.setdefault('labels', {})  # labelname -> docname, labelid, sectionname
+        return self.data.setdefault(
+            'labels', {}
+        )  # labelname -> docname, labelid, sectionname
 
     @property
     def anonlabels(self) -> dict[str, tuple[str, str]]:
         return self.data.setdefault('anonlabels', {})  # labelname -> docname, labelid
 
     def clear_doc(self, docname: str) -> None:
-        key: Any = None
-        for key, (fn, _l) in list(self.progoptions.items()):
-            if fn == docname:
-                del self.progoptions[key]
-        for key, (fn, _l) in list(self.objects.items()):
-            if fn == docname:
-                del self.objects[key]
-        for key, (fn, _l) in list(self._terms.items()):
-            if fn == docname:
-                del self._terms[key]
-        for key, (fn, _l, _l) in list(self.labels.items()):
-            if fn == docname:
-                del self.labels[key]
-        for key, (fn, _l) in list(self.anonlabels.items()):
-            if fn == docname:
-                del self.anonlabels[key]
+        to_remove1 = [
+            key for key, (fn, _l) in self.progoptions.items() if fn == docname
+        ]
+        for key1 in to_remove1:
+            del self.progoptions[key1]
+
+        to_remove2 = [key for key, (fn, _l) in self.objects.items() if fn == docname]
+        for key2 in to_remove2:
+            del self.objects[key2]
+
+        to_remove3 = [key for key, (fn, _l) in self._terms.items() if fn == docname]
+        for key3 in to_remove3:
+            del self._terms[key3]
+
+        to_remove3 = [key for key, (fn, _l, _l) in self.labels.items() if fn == docname]
+        for key3 in to_remove3:
+            del self.labels[key3]
+
+        to_remove3 = [key for key, (fn, _l) in self.anonlabels.items() if fn == docname]
+        for key3 in to_remove3:
+            del self.anonlabels[key3]
 
     def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         # XXX duplicates?
@@ -785,7 +934,7 @@ class StandardDomain(Domain):
                 self.anonlabels[key] = data
 
     def process_doc(
-        self, env: BuildEnvironment, docname: str, document: nodes.document,
+        self, env: BuildEnvironment, docname: str, document: nodes.document
     ) -> None:
         for name, explicit in document.nametypes.items():
             if not explicit:
@@ -798,19 +947,24 @@ class StandardDomain(Domain):
                 # indirect hyperlink targets
                 node = document.ids.get(node['refid'])  # type: ignore[assignment]
                 labelid = node['names'][0]
-            if (node.tagname == 'footnote' or
-                    'refuri' in node or
-                    node.tagname.startswith('desc_')):
+            if (
+                node.tagname == 'footnote'
+                or 'refuri' in node
+                or node.tagname.startswith('desc_')
+            ):
                 # ignore footnote labels, labels automatically generated from a
                 # link and object descriptions
                 continue
             if name in self.labels:
-                logger.warning(__('duplicate label %s, other instance in %s'),
-                               name, env.doc2path(self.labels[name][0]),
-                               location=node)
+                logger.warning(
+                    __('duplicate label %s, other instance in %s'),
+                    name,
+                    env.doc2path(self.labels[name][0]),
+                    location=node,
+                )
             self.anonlabels[name] = docname, labelid
             if node.tagname == 'section':
-                title = cast(nodes.title, node[0])
+                title = cast('nodes.title', node[0])
                 sectname = clean_astext(title)
             elif node.tagname == 'rubric':
                 sectname = clean_astext(node)
@@ -819,11 +973,13 @@ class StandardDomain(Domain):
                 if not sectname:
                     continue
             else:
-                if (isinstance(node, nodes.definition_list | nodes.field_list) and
-                        node.children):
-                    node = cast(nodes.Element, node.children[0])
+                if (
+                    isinstance(node, nodes.definition_list | nodes.field_list)
+                    and node.children
+                ):
+                    node = cast('nodes.Element', node.children[0])
                 if isinstance(node, nodes.field | nodes.definition_list_item):
-                    node = cast(nodes.Element, node.children[0])
+                    node = cast('nodes.Element', node.children[0])
                 if isinstance(node, nodes.term | nodes.field_name):
                     sectname = clean_astext(node)
                 else:
@@ -835,17 +991,26 @@ class StandardDomain(Domain):
                         continue
             self.labels[name] = docname, labelid, sectname
 
-    def add_program_option(self, program: str | None, name: str,
-                           docname: str, labelid: str) -> None:
+    def add_program_option(
+        self, program: str | None, name: str, docname: str, labelid: str
+    ) -> None:
         # prefer first command option entry
         if (program, name) not in self.progoptions:
             self.progoptions[program, name] = (docname, labelid)
 
-    def build_reference_node(self, fromdocname: str, builder: Builder, docname: str,
-                             labelid: str, sectname: str, rolename: str, **options: Any,
-                             ) -> Element:
-        nodeclass = options.pop('nodeclass', nodes.reference)
-        newnode = nodeclass('', '', internal=True, **options)
+    def build_reference_node(
+        self,
+        fromdocname: str,
+        builder: Builder,
+        docname: str,
+        labelid: str,
+        sectname: str,
+        rolename: str,
+        *,
+        node_class: type[nodes.reference] = nodes.reference,
+        **options: Any,
+    ) -> nodes.reference:
+        newnode = node_class('', '', internal=True, **options)
         innernode = nodes.inline(sectname, sectname)
         if innernode.get('classes') is not None:
             innernode['classes'].append('std')
@@ -859,20 +1024,26 @@ class StandardDomain(Domain):
             contnode = pending_xref('')
             contnode['refdocname'] = docname
             contnode['refsectname'] = sectname
-            newnode['refuri'] = builder.get_relative_uri(
-                fromdocname, docname)
+            newnode['refuri'] = builder.get_relative_uri(fromdocname, docname)
             if labelid:
                 newnode['refuri'] += '#' + labelid
         newnode.append(innernode)
         return newnode
 
-    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                     typ: str, target: str, node: pending_xref, contnode: Element,
-                     ) -> Element | None:
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         if typ == 'ref':
             resolver = self._resolve_ref_xref
         elif typ == 'numref':
-            resolver = self._resolve_numref_xref
+            resolver = self._resolve_numref_xref  # type: ignore[assignment]
         elif typ == 'keyword':
             resolver = self._resolve_keyword_xref
         elif typ == 'doc':
@@ -886,9 +1057,16 @@ class StandardDomain(Domain):
 
         return resolver(env, fromdocname, builder, typ, target, node, contnode)
 
-    def _resolve_ref_xref(self, env: BuildEnvironment, fromdocname: str,
-                          builder: Builder, typ: str, target: str, node: pending_xref,
-                          contnode: Element) -> Element | None:
+    def _resolve_ref_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         if node['refexplicit']:
             # reference to anonymous label; the reference uses
             # the supplied link caption
@@ -901,12 +1079,20 @@ class StandardDomain(Domain):
         if not docname:
             return None
 
-        return self.build_reference_node(fromdocname, builder,
-                                         docname, labelid, sectname, 'ref')
+        return self.build_reference_node(
+            fromdocname, builder, docname, labelid, sectname, 'ref'
+        )
 
-    def _resolve_numref_xref(self, env: BuildEnvironment, fromdocname: str,
-                             builder: Builder, typ: str, target: str,
-                             node: pending_xref, contnode: Element) -> Element | None:
+    def _resolve_numref_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | Element | None:
         if target in self.labels:
             docname, labelid, figname = self.labels.get(target, ('', '', ''))
         else:
@@ -923,7 +1109,9 @@ class StandardDomain(Domain):
             return None
 
         if figtype != 'section' and env.config.numfig is False:
-            logger.warning(__('numfig is disabled. :numref: is ignored.'), location=node)
+            logger.warning(
+                __('numfig is disabled. :numref: is ignored.'), location=node
+            )
             return contnode
 
         try:
@@ -931,9 +1119,13 @@ class StandardDomain(Domain):
             if fignumber is None:
                 return contnode
         except ValueError:
-            logger.warning(__("Failed to create a cross reference. Any number is not "
-                              "assigned: %s"),
-                           labelid, location=node)
+            logger.warning(
+                __(
+                    'Failed to create a cross reference. Any number is not assigned: %s'
+                ),
+                labelid,
+                location=node,
+            )
             return contnode
 
         try:
@@ -957,30 +1149,51 @@ class StandardDomain(Domain):
                     # old style format (cf. "Fig.%s")
                     newtitle = title % fignum
         except KeyError as exc:
-            logger.warning(__('invalid numfig_format: %s (%r)'), title, exc, location=node)
+            logger.warning(
+                __('invalid numfig_format: %s (%r)'), title, exc, location=node
+            )
             return contnode
         except TypeError:
             logger.warning(__('invalid numfig_format: %s'), title, location=node)
             return contnode
 
-        return self.build_reference_node(fromdocname, builder,
-                                         docname, labelid, newtitle, 'numref',
-                                         nodeclass=addnodes.number_reference,
-                                         title=title)
+        return self.build_reference_node(
+            fromdocname,
+            builder,
+            docname,
+            labelid,
+            newtitle,
+            'numref',
+            node_class=addnodes.number_reference,
+            title=title,
+        )
 
-    def _resolve_keyword_xref(self, env: BuildEnvironment, fromdocname: str,
-                              builder: Builder, typ: str, target: str,
-                              node: pending_xref, contnode: Element) -> Element | None:
+    def _resolve_keyword_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         # keywords are oddballs: they are referenced by named labels
         docname, labelid, _ = self.labels.get(target, ('', '', ''))
         if not docname:
             return None
-        return make_refnode(builder, fromdocname, docname,
-                            labelid, contnode)
+        return make_refnode(builder, fromdocname, docname, labelid, contnode)
 
-    def _resolve_doc_xref(self, env: BuildEnvironment, fromdocname: str,
-                          builder: Builder, typ: str, target: str,
-                          node: pending_xref, contnode: Element) -> Element | None:
+    def _resolve_doc_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         # directly reference to document by source name; can be absolute or relative
         refdoc = node.get('refdoc', fromdocname)
         docname = docname_join(refdoc, node['reftarget'])
@@ -995,9 +1208,16 @@ class StandardDomain(Domain):
             innernode = nodes.inline(caption, caption, classes=['doc'])
             return make_refnode(builder, fromdocname, docname, None, innernode)
 
-    def _resolve_option_xref(self, env: BuildEnvironment, fromdocname: str,
-                             builder: Builder, typ: str, target: str,
-                             node: pending_xref, contnode: Element) -> Element | None:
+    def _resolve_option_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         progname = node.get('std:program')
         target = target.strip()
         docname, labelid = self.progoptions.get((progname, target), ('', ''))
@@ -1017,7 +1237,7 @@ class StandardDomain(Domain):
             while ws_re.search(target):
                 subcommand, target = ws_re.split(target, 1)
                 commands.append(subcommand)
-                progname = "-".join(commands)
+                progname = '-'.join(commands)
 
                 docname, labelid = self.progoptions.get((progname, target), ('', ''))
                 if docname:
@@ -1025,14 +1245,21 @@ class StandardDomain(Domain):
             else:
                 return None
 
-        return make_refnode(builder, fromdocname, docname,
-                            labelid, contnode)
+        return make_refnode(builder, fromdocname, docname, labelid, contnode)
 
-    def _resolve_term_xref(self, env: BuildEnvironment, fromdocname: str,
-                           builder: Builder, typ: str, target: str,
-                           node: pending_xref, contnode: Element) -> Element | None:
-        result = self._resolve_obj_xref(env, fromdocname, builder, typ,
-                                        target, node, contnode)
+    def _resolve_term_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
+        result = self._resolve_obj_xref(
+            env, fromdocname, builder, typ, target, node, contnode
+        )
         if result:
             return result
         else:
@@ -1043,9 +1270,16 @@ class StandardDomain(Domain):
             else:
                 return None
 
-    def _resolve_obj_xref(self, env: BuildEnvironment, fromdocname: str,
-                          builder: Builder, typ: str, target: str,
-                          node: pending_xref, contnode: Element) -> Element | None:
+    def _resolve_obj_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> nodes.reference | None:
         objtypes = self.objtypes_for_role(typ) or []
         for objtype in objtypes:
             if (objtype, target) in self.objects:
@@ -1055,18 +1289,29 @@ class StandardDomain(Domain):
             docname, labelid = '', ''
         if not docname:
             return None
-        return make_refnode(builder, fromdocname, docname,
-                            labelid, contnode)
+        return make_refnode(builder, fromdocname, docname, labelid, contnode)
 
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str,
-                         builder: Builder, target: str, node: pending_xref,
-                         contnode: Element) -> list[tuple[str, Element]]:
-        results: list[tuple[str, Element]] = []
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> list[tuple[str, nodes.reference]]:
+        results: list[tuple[str, nodes.reference]] = []
         ltarget = target.lower()  # :ref: lowercases its target automatically
         for role in ('ref', 'option'):  # do not try "keyword"
-            res = self.resolve_xref(env, fromdocname, builder, role,
-                                    ltarget if role == 'ref' else target,
-                                    node, contnode)
+            res = self.resolve_xref(
+                env,
+                fromdocname,
+                builder,
+                role,
+                ltarget if role == 'ref' else target,
+                node,
+                contnode,
+            )
             if res:
                 results.append(('std:' + role, res))
         # all others
@@ -1077,30 +1322,38 @@ class StandardDomain(Domain):
             if key in self.objects:
                 docname, labelid = self.objects[key]
                 role = 'std:' + self.role_for_objtype(objtype)  # type: ignore[operator]
-                results.append((role, make_refnode(builder, fromdocname, docname,
-                                                   labelid, contnode)))
+                results.append((
+                    role,
+                    make_refnode(builder, fromdocname, docname, labelid, contnode),
+                ))
         return results
 
     def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
         # handle the special 'doc' reference here
         for doc in self.env.all_docs:
-            yield (doc, clean_astext(self.env.titles[doc]), 'doc', doc, '', -1)
+            yield doc, clean_astext(self.env.titles[doc]), 'doc', doc, '', -1
         for (prog, option), info in self.progoptions.items():
             if prog:
                 fullname = f'{prog}.{option}'
-                yield (fullname, fullname, 'cmdoption', info[0], info[1], 1)
+                yield fullname, fullname, 'cmdoption', info[0], info[1], 1
             else:
-                yield (option, option, 'cmdoption', info[0], info[1], 1)
+                yield option, option, 'cmdoption', info[0], info[1], 1
         for (type, name), info in self.objects.items():
-            yield (name, name, type, info[0], info[1],
-                   self.object_types[type].attrs['searchprio'])
+            yield (
+                name,
+                name,
+                type,
+                info[0],
+                info[1],
+                self.object_types[type].attrs['searchprio'],
+            )
         for name, (docname, labelid, sectionname) in self.labels.items():
-            yield (name, sectionname, 'label', docname, labelid, -1)
+            yield name, sectionname, 'label', docname, labelid, -1
         # add anonymous-only labels as well
         non_anon_labels = set(self.labels)
         for name, (docname, labelid) in self.anonlabels.items():
             if name not in non_anon_labels:
-                yield (name, name, 'label', docname, labelid, -1)
+                yield name, name, 'label', docname, labelid, -1
 
     def get_type_name(self, type: ObjType, primary: bool = False) -> str:
         # never prepend "Default"
@@ -1112,7 +1365,7 @@ class StandardDomain(Domain):
     def get_numfig_title(self, node: Node) -> str | None:
         """Get the title of enumerable nodes to refer them using its title"""
         if self.is_enumerable_node(node):
-            elem = cast(Element, node)
+            elem = cast('Element', node)
             _, title_getter = self.enumerable_nodes.get(elem.__class__, (None, None))
             if title_getter:
                 return title_getter(elem)
@@ -1125,14 +1378,17 @@ class StandardDomain(Domain):
 
     def get_enumerable_node_type(self, node: Node) -> str | None:
         """Get type of enumerable nodes."""
+
         def has_child(node: Element, cls: type) -> bool:
             return any(isinstance(child, cls) for child in node)
 
         if isinstance(node, nodes.section):
             return 'section'
-        elif (isinstance(node, nodes.container) and
-              'literal_block' in node and
-              has_child(node, nodes.literal_block)):
+        elif (
+            isinstance(node, nodes.container)
+            and 'literal_block' in node
+            and has_child(node, nodes.literal_block)
+        ):
             # given node is a code-block having caption
             return 'code-block'
         else:
@@ -1184,8 +1440,11 @@ class StandardDomain(Domain):
             return None
 
 
-def warn_missing_reference(app: Sphinx, domain: Domain, node: pending_xref,
-                           ) -> bool | None:
+def warn_missing_reference(
+    app: Sphinx,
+    domain: Domain,
+    node: pending_xref,
+) -> bool | None:
     if (domain and domain.name != 'std') or node['reftype'] != 'ref':
         return None
     else:
@@ -1193,7 +1452,9 @@ def warn_missing_reference(app: Sphinx, domain: Domain, node: pending_xref,
         if target not in domain.anonlabels:  # type: ignore[attr-defined]
             msg = __('undefined label: %r')
         else:
-            msg = __('Failed to create a cross reference. A title or caption not found: %r')
+            msg = __(
+                'Failed to create a cross reference. A title or caption not found: %r'
+            )
 
         logger.warning(msg, target, location=node, type='ref', subtype=node['reftype'])
         return True