py2docfx 0.1.10.dev1859594__py3-none-any.whl → 0.1.10.dev1870645__py3-none-any.whl

py2docfx/venv/venv0/Lib/site-packages/sphinx/domains/std.py

@@ -0,0 +1,1155 @@
+"""The standard domain."""
+
+from __future__ import annotations
+
+import re
+from copy import copy
+from typing import TYPE_CHECKING, Any, Callable, Final, Iterable, Iterator, cast
+
+from docutils import nodes
+from docutils.nodes import Element, Node, system_message
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+
+from sphinx import addnodes
+from sphinx.addnodes import desc_signature, pending_xref
+from sphinx.directives import ObjectDescription
+from sphinx.domains import Domain, ObjType, TitleGetter
+from sphinx.locale import _, __
+from sphinx.roles import EmphasizedLiteral, XRefRole
+from sphinx.util import docname_join, logging, ws_re
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import clean_astext, make_id, make_refnode
+from sphinx.util.typing import OptionSpec, RoleFunction
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
+
+logger = logging.getLogger(__name__)
+
+# RE for option descriptions
+option_desc_re = re.compile(r'((?:/|--|-|\+)?[^\s=]+)(=?\s*.*)')
+# RE for grammar tokens
+token_re = re.compile(r'`((~?\w*:)?\w+)`', re.U)
+
+samp_role = EmphasizedLiteral()
+
+
+class GenericObject(ObjectDescription[str]):
+    """
+    A generic x-ref directive registered with Sphinx.add_object_type().
+    """
+    indextemplate: str = ''
+    parse_node: Callable[[BuildEnvironment, str, desc_signature], str] | None = None
+
+    def handle_signature(self, sig: str, signode: desc_signature) -> str:
+        if self.parse_node:
+            name = self.parse_node(self.env, sig, signode)
+        else:
+            signode.clear()
+            signode += addnodes.desc_name(sig, sig)
+            # normalize whitespace like XRefRole does
+            name = ws_re.sub(' ', sig)
+        return name
+
+    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)
+
+        if self.indextemplate:
+            colon = self.indextemplate.find(':')
+            if colon != -1:
+                indextype = self.indextemplate[:colon].strip()
+                indexentry = self.indextemplate[colon + 1:].strip() % (name,)
+            else:
+                indextype = 'single'
+                indexentry = self.indextemplate % (name,)
+            self.indexnode['entries'].append((indextype, indexentry, node_id, '', None))
+
+        std = cast(StandardDomain, self.env.get_domain('std'))
+        std.note_object(self.objtype, name, node_id, location=signode)
+
+    def make_old_id(self, name: str) -> str:
+        """Generate old styled node_id for generic objects.
+
+        .. note:: Old Styled node_id was used until Sphinx-3.0.
+                  This will be removed in Sphinx-5.0.
+        """
+        return self.objtype + '-' + name
+
+
+class EnvVar(GenericObject):
+    indextemplate = _('environment variable; %s')
+
+
+class EnvVarXRefRole(XRefRole):
+    """
+    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]]:
+        if not is_ref:
+            return [node], []
+        varname = node['reftarget']
+        tgtid = 'index-%s' % env.new_serialno('index')
+        indexnode = addnodes.index()
+        indexnode['entries'] = [
+            ('single', varname, tgtid, '', None),
+            ('single', _('environment variable; %s') % varname, tgtid, '', None)
+        ]
+        targetnode = nodes.target('', '', ids=[tgtid])
+        document.note_explicit_target(targetnode)
+        return [indexnode, targetnode, node], []
+
+
+class Target(SphinxDirective):
+    """
+    Generic target for user-defined cross-reference types.
+    """
+    indextemplate = ''
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec: OptionSpec = {}
+
+    def run(self) -> list[Node]:
+        # normalize whitespace in fullname like XRefRole does
+        fullname = ws_re.sub(' ', self.arguments[0].strip())
+        node_id = make_id(self.env, self.state.document, self.name, fullname)
+        node = nodes.target('', '', ids=[node_id])
+        self.set_source_info(node)
+        self.state.document.note_explicit_target(node)
+        ret: list[Node] = [node]
+        if self.indextemplate:
+            indexentry = self.indextemplate % (fullname,)
+            indextype = 'single'
+            colon = indexentry.find(':')
+            if colon != -1:
+                indextype = indexentry[:colon].strip()
+                indexentry = indexentry[colon + 1:].strip()
+            inode = addnodes.index(entries=[(indextype, indexentry, node_id, '', None)])
+            ret.insert(0, inode)
+        name = self.name
+        if ':' in self.name:
+            _, name = self.name.split(':', 1)
+
+        std = cast(StandardDomain, self.env.get_domain('std'))
+        std.note_object(name, fullname, node_id, location=node)
+
+        return ret
+
+    def make_old_id(self, name: str) -> str:
+        """Generate old styled node_id for targets.
+
+        .. note:: Old Styled node_id was used until Sphinx-3.0.
+                  This will be removed in Sphinx-5.0.
+        """
+        return self.name + '-' + name
+
+
+class Cmdoption(ObjectDescription[str]):
+    """
+    Description of a command-line option (.. option).
+    """
+
+    def handle_signature(self, sig: str, signode: desc_signature) -> str:
+        """Transform an option description into RST nodes."""
+        count = 0
+        firstname = ''
+        for potential_option in sig.split(', '):
+            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)
+                continue
+            optname, args = m.groups()
+            if optname[-1] == '[' and args[-1] == ']':
+                # optional value surrounded by brackets (ex. foo[=bar])
+                optname = optname[:-1]
+                args = '[' + args
+
+            if count:
+                if self.env.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:
+                add_end_bracket = False
+                if args:
+                    if args[0] == '[' and args[-1] == ']':
+                        add_end_bracket = True
+                        signode += addnodes.desc_sig_punctuation('[', '[')
+                        args = args[1:-1]
+                    elif args[0] == ' ':
+                        signode += addnodes.desc_sig_space()
+                        args = args.strip()
+                    elif args[0] == '=':
+                        signode += addnodes.desc_sig_punctuation('=', '=')
+                        args = args[1:]
+                    for part in samp_role.parse(args):
+                        if isinstance(part, nodes.Text):
+                            signode += nodes.Text(part.astext())
+                        else:
+                            signode += part
+                if add_end_bracket:
+                    signode += addnodes.desc_sig_punctuation(']', ']')
+            else:
+                signode += addnodes.desc_addname(args, args)
+            if not count:
+                firstname = optname
+                signode['allnames'] = [optname]
+            else:
+                signode['allnames'].append(optname)
+            count += 1
+        if not firstname:
+            raise ValueError
+        return firstname
+
+    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', []):
+            prefixes = ['cmdoption']
+            if currprogram:
+                prefixes.append(currprogram)
+            if not optname.startswith(('-', '/')):
+                prefixes.append('arg')
+            prefix = '-'.join(prefixes)
+            node_id = make_id(self.env, self.state.document, prefix, optname)
+            signode['ids'].append(node_id)
+
+            old_node_id = self.make_old_id(prefix, optname)
+            if old_node_id not in self.state.document.ids and \
+               old_node_id not in signode['ids']:
+                signode['ids'].append(old_node_id)
+
+        self.state.document.note_explicit_target(signode)
+
+        domain = cast(StandardDomain, self.env.get_domain('std'))
+        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', []):
+            entry = '; '.join([descr, option])
+            self.indexnode['entries'].append(('pair', entry, signode['ids'][0], '', None))
+
+    def make_old_id(self, prefix: str, optname: str) -> str:
+        """Generate old styled node_id for cmdoption.
+
+        .. note:: Old Styled node_id was used until Sphinx-3.0.
+                  This will be removed in Sphinx-5.0.
+        """
+        return nodes.make_id(prefix + '-' + optname)
+
+
+class Program(SphinxDirective):
+    """
+    Directive to name the program for which options are documented.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec: OptionSpec = {}
+
+    def run(self) -> list[Node]:
+        program = ws_re.sub('-', self.arguments[0].strip())
+        if program == 'None':
+            self.env.ref_context.pop('std:program', None)
+        else:
+            self.env.ref_context['std:program'] = program
+        return []
+
+
+class OptionXRefRole(XRefRole):
+    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
+
+
+def split_term_classifiers(line: str) -> list[str | None]:
+    # split line into a term and classifiers. if no classifier, None is used..
+    parts: list[str | None] = re.split(' +: +', line) + [None]
+    return parts
+
+
+def make_glossary_term(env: BuildEnvironment, textnodes: Iterable[Node], index_key: str,
+                       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)
+    term.source = source
+    term.line = lineno
+    termtext = term.astext()
+
+    if node_id:
+        # node_id is given from outside (mainly i18n module), use it forcedly
+        term['ids'].append(node_id)
+    else:
+        node_id = make_id(env, document, 'term', termtext)
+        term['ids'].append(node_id)
+        document.note_explicit_target(term)
+
+    std = cast(StandardDomain, env.get_domain('std'))
+    std._note_term(termtext, node_id, location=term)
+
+    # add an index entry too
+    indexnode = addnodes.index()
+    indexnode['entries'] = [('single', termtext, node_id, 'main', index_key)]
+    indexnode.source, indexnode.line = term.source, term.line
+    term.append(indexnode)
+
+    return term
+
+
+class Glossary(SphinxDirective):
+    """
+    Directive to create a glossary with cross-reference targets for :term:
+    roles.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec: OptionSpec = {
+        'sorted': directives.flag,
+    }
+
+    def run(self) -> list[Node]:
+        node = addnodes.glossary()
+        node.document = self.state.document
+        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
+        # easy to parse since we know that the contents of the glossary *must
+        # be* a definition list.
+
+        # first, collect single entries
+        entries: list[tuple[list[tuple[str, str, int]], StringList]] = []
+        in_definition = True
+        in_comment = False
+        was_empty = True
+        messages: list[Node] = []
+        for line, (source, lineno) in zip(self.content, self.content.items):
+            # empty line -> add to last definition
+            if not line:
+                if in_definition and entries:
+                    entries[-1][1].append('', source, lineno)
+                was_empty = True
+                continue
+            # unindented line -> a term
+            if line and not line[0].isspace():
+                # enable comments
+                if line.startswith('.. '):
+                    in_comment = True
+                    continue
+                else:
+                    in_comment = False
+
+                # 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))
+                    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))
+                    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))
+            elif in_comment:
+                pass
+            else:
+                if not in_definition:
+                    # first line of definition, determines indentation
+                    in_definition = True
+                    indent_len = len(line) - len(line.lstrip())
+                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))
+            was_empty = False
+
+        # now, parse all the entries into a big definition list
+        items: list[nodes.definition_list_item] = []
+        for terms, definition in entries:
+            termnodes: list[Node] = []
+            system_messages: list[Node] = []
+            for line, source, lineno in terms:
+                parts = split_term_classifiers(line)
+                # parse the term with inline markup
+                # classifiers (parts[1:]) will not be shown on doctree
+                textnodes, sysmsg = self.state.inline_text(parts[0], lineno)
+
+                # use first classifier as a index key
+                term = make_glossary_term(self.env, textnodes, parts[1], source, lineno,
+                                          node_id=None, document=self.state.document)
+                term.rawsource = line
+                system_messages.extend(sysmsg)
+                termnodes.append(term)
+
+            termnodes.extend(system_messages)
+
+            defnode = nodes.definition()
+            if definition:
+                self.state.nested_parse(definition, definition.items[0][1],
+                                        defnode)
+            termnodes.append(defnode)
+            items.append(nodes.definition_list_item('', *termnodes))
+
+        dlist = nodes.definition_list('', *items)
+        dlist['classes'].append('glossary')
+        node += dlist
+        return messages + [node]
+
+
+def token_xrefs(text: str, productionGroup: str = '') -> list[Node]:
+    if len(productionGroup) != 0:
+        productionGroup += ':'
+    retnodes: list[Node] = []
+    pos = 0
+    for m in token_re.finditer(text):
+        if m.start() > pos:
+            txt = text[pos:m.start()]
+            retnodes.append(nodes.Text(txt))
+        token = m.group(1)
+        if ':' in token:
+            if token[0] == '~':
+                _, title = token.split(':')
+                target = token[1:]
+            elif token[0] == ':':
+                title = token[1:]
+                target = title
+            else:
+                title = token
+                target = token
+        else:
+            title = token
+            target = productionGroup + token
+        refnode = pending_xref(title, reftype='token', refdomain='std',
+                               reftarget=target)
+        refnode += nodes.literal(token, title, classes=['xref'])
+        retnodes.append(refnode)
+        pos = m.end()
+    if pos < len(text):
+        retnodes.append(nodes.Text(text[pos:]))
+    return retnodes
+
+
+class ProductionList(SphinxDirective):
+    """
+    Directive to list grammar productions.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec: OptionSpec = {}
+
+    def run(self) -> list[Node]:
+        domain = cast(StandardDomain, self.env.get_domain('std'))
+        node: Element = addnodes.productionlist()
+        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]
+
+    def make_old_id(self, token: str) -> str:
+        """Generate old styled node_id for tokens.
+
+        .. note:: Old Styled node_id was used until Sphinx-3.0.
+                  This will be removed in Sphinx-5.0.
+        """
+        return nodes.make_id('grammar-token-' + token)
+
+
+class TokenXRefRole(XRefRole):
+    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:
+                _, title = title.split(':')
+            else:
+                title = title[1:]
+        return title, target
+
+
+class StandardDomain(Domain):
+    """
+    Domain for all objects that don't fit into another domain or are added
+    via the application interface.
+    """
+
+    name = 'std'
+    label = 'Default'
+
+    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),
+        'envvar': ObjType(_('environment variable'), 'envvar'),
+        'cmdoption': ObjType(_('program option'), 'option'),
+        'doc': ObjType(_('document'), 'doc', searchprio=-1)
+    }
+
+    directives: dict[str, type[Directive]] = {
+        'program': Program,
+        'cmdoption': Cmdoption,  # old name for backwards compatibility
+        'option': Cmdoption,
+        'envvar': EnvVar,
+        'glossary': Glossary,
+        'productionlist': ProductionList,
+    }
+    roles: dict[str, RoleFunction | XRefRole] = {
+        'option':  OptionXRefRole(warn_dangling=True),
+        'envvar':  EnvVarXRefRole(),
+        # links to tokens in grammar productions
+        'token':   TokenXRefRole(),
+        # links to terms in glossary
+        'term':    XRefRole(innernodeclass=nodes.inline,
+                            warn_dangling=True),
+        # links to headings or arbitrary labels
+        '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),
+        # links to labels, without a different title
+        'keyword': XRefRole(warn_dangling=True),
+        # links to documents
+        '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
+            'genindex': ('genindex', '', _('Index')),
+            'modindex': ('py-modindex', '', _('Module Index')),
+            'search':   ('search', '', _('Search Page')),
+        },
+        'anonlabels': {         # labelname -> docname, labelid
+            'genindex': ('genindex', ''),
+            'modindex': ('py-modindex', ''),
+            'search':   ('search', ''),
+        },
+    }
+
+    _virtual_doc_names: dict[str, tuple[str, str]] = {  # labelname -> docname, sectionname
+        'genindex': ('genindex', _('Index')),
+        'modindex': ('py-modindex', _('Module Index')),
+        'search': ('search', _('Search Page')),
+    }
+
+    dangling_warnings = {
+        'term': 'term not in glossary: %(target)r',
+        'numref':  'undefined label: %(target)r',
+        'keyword': 'unknown keyword: %(target)r',
+        'doc': 'unknown document: %(target)r',
+        'option': 'unknown option: %(target)r',
+    }
+
+    # node_class -> (figtype, title_getter)
+    enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {
+        nodes.figure: ('figure', None),
+        nodes.table: ('table', None),
+        nodes.container: ('code-block', None),
+    }
+
+    def __init__(self, env: BuildEnvironment) -> None:
+        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[node] = settings
+
+    def note_hyperlink_target(self, name: str, docname: str, node_id: str,
+                              title: str = '') -> None:
+        """Add a hyperlink target for cross reference.
+
+        .. warning::
+
+           This is only for internal use.  Please don't use this from your extension.
+           ``document.note_explicit_target()`` or ``note_implicit_target()`` are recommended to
+           add a hyperlink target to the document.
+
+           This only adds a hyperlink target to the StandardDomain.  And this does not add a
+           node_id to node.  Therefore, it is very fragile to calling this without
+           understanding hyperlink target framework in both docutils and Sphinx.
+
+        .. 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]))
+
+        self.anonlabels[name] = (docname, node_id)
+        if title:
+            self.labels[name] = (docname, node_id, title)
+
+    @property
+    def objects(self) -> dict[tuple[str, str], tuple[str, str]]:
+        return self.data.setdefault('objects', {})  # (objtype, name) -> docname, labelid
+
+    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)
+        self.objects[objtype, name] = (self.env.docname, labelid)
+
+    @property
+    def _terms(self) -> dict[str, tuple[str, str]]:
+        """.. note:: Will be removed soon. internal use only."""
+        return self.data.setdefault('terms', {})  # (name) -> docname, labelid
+
+    def _note_term(self, term: str, labelid: str, location: Any = None) -> None:
+        """Note a term for cross reference.
+
+        .. note:: Will be removed soon. internal use only.
+        """
+        self.note_object('term', term, labelid, location)
+
+        self._terms[term.lower()] = (self.env.docname, labelid)
+
+    @property
+    def progoptions(self) -> dict[tuple[str, str], tuple[str, str]]:
+        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
+
+    @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]
+
+    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+        # XXX duplicates?
+        for key, data in otherdata['progoptions'].items():
+            if data[0] in docnames:
+                self.progoptions[key] = data
+        for key, data in otherdata['objects'].items():
+            if data[0] in docnames:
+                self.objects[key] = data
+        for key, data in otherdata['terms'].items():
+            if data[0] in docnames:
+                self._terms[key] = data
+        for key, data in otherdata['labels'].items():
+            if data[0] in docnames:
+                self.labels[key] = data
+        for key, data in otherdata['anonlabels'].items():
+            if data[0] in docnames:
+                self.anonlabels[key] = data
+
+    def process_doc(
+        self, env: BuildEnvironment, docname: str, document: nodes.document
+    ) -> None:
+        for name, explicit in document.nametypes.items():
+            if not explicit:
+                continue
+            labelid = document.nameids[name]
+            if labelid is None:
+                continue
+            node = document.ids[labelid]
+            if isinstance(node, nodes.target) and 'refid' in node:
+                # indirect hyperlink targets
+                node = document.ids.get(node['refid'])
+                labelid = node['names'][0]
+            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)
+            self.anonlabels[name] = docname, labelid
+            if node.tagname == 'section':
+                title = cast(nodes.title, node[0])
+                sectname: str | None = clean_astext(title)
+            elif node.tagname == 'rubric':
+                sectname = clean_astext(node)
+            elif self.is_enumerable_node(node):
+                sectname = self.get_numfig_title(node)
+                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.field, nodes.definition_list_item)):
+                    node = cast(nodes.Element, node.children[0])
+                if isinstance(node, (nodes.term, nodes.field_name)):
+                    sectname = clean_astext(node)
+                else:
+                    toctree = next(node.findall(addnodes.toctree), None)
+                    if toctree and toctree.get('caption'):
+                        sectname = toctree.get('caption')
+                    else:
+                        # anonymous-only labels
+                        continue
+            self.labels[name] = docname, labelid, sectname
+
+    def add_program_option(self, program: str, 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)
+        innernode = nodes.inline(sectname, sectname)
+        if innernode.get('classes') is not None:
+            innernode['classes'].append('std')
+            innernode['classes'].append('std-' + rolename)
+        if docname == fromdocname:
+            newnode['refid'] = labelid
+        else:
+            # set more info in contnode; in case the
+            # get_relative_uri call raises NoUri,
+            # the builder will then have to resolve these
+            contnode = pending_xref('')
+            contnode['refdocname'] = docname
+            contnode['refsectname'] = sectname
+            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:
+        if typ == 'ref':
+            resolver = self._resolve_ref_xref
+        elif typ == 'numref':
+            resolver = self._resolve_numref_xref
+        elif typ == 'keyword':
+            resolver = self._resolve_keyword_xref
+        elif typ == 'doc':
+            resolver = self._resolve_doc_xref
+        elif typ == 'option':
+            resolver = self._resolve_option_xref
+        elif typ == 'term':
+            resolver = self._resolve_term_xref
+        else:
+            resolver = self._resolve_obj_xref
+
+        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:
+        if node['refexplicit']:
+            # reference to anonymous label; the reference uses
+            # the supplied link caption
+            docname, labelid = self.anonlabels.get(target, ('', ''))
+            sectname = node.astext()
+        else:
+            # reference to named label; the final node will
+            # contain the section name after the label
+            docname, labelid, sectname = self.labels.get(target, ('', '', ''))
+        if not docname:
+            return None
+
+        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:
+        if target in self.labels:
+            docname, labelid, figname = self.labels.get(target, ('', '', ''))
+        else:
+            docname, labelid = self.anonlabels.get(target, ('', ''))
+            figname = None
+
+        if not docname:
+            return None
+
+        target_node = env.get_doctree(docname).ids.get(labelid)
+        figtype = self.get_enumerable_node_type(target_node)
+        if figtype is None:
+            return None
+
+        if figtype != 'section' and env.config.numfig is False:
+            logger.warning(__('numfig is disabled. :numref: is ignored.'), location=node)
+            return contnode
+
+        try:
+            fignumber = self.get_fignumber(env, builder, figtype, docname, target_node)
+            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)
+            return contnode
+
+        try:
+            if node['refexplicit']:
+                title = contnode.astext()
+            else:
+                title = env.config.numfig_format.get(figtype, '')
+
+            if figname is None and '{name}' in title:
+                logger.warning(__('the link has no caption: %s'), title, location=node)
+                return contnode
+            else:
+                fignum = '.'.join(map(str, fignumber))
+                if '{name}' in title or 'number' in title:
+                    # new style format (cf. "Fig.{number}")
+                    if figname:
+                        newtitle = title.format(name=figname, number=fignum)
+                    else:
+                        newtitle = title.format(number=fignum)
+                else:
+                    # old style format (cf. "Fig.%s")
+                    newtitle = title % fignum
+        except KeyError as exc:
+            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)
+
+    def _resolve_keyword_xref(self, env: BuildEnvironment, fromdocname: str,
+                              builder: Builder, typ: str, target: str,
+                              node: pending_xref, contnode: Element) -> Element | 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)
+
+    def _resolve_doc_xref(self, env: BuildEnvironment, fromdocname: str,
+                          builder: Builder, typ: str, target: str,
+                          node: pending_xref, contnode: Element) -> Element | None:
+        # directly reference to document by source name; can be absolute or relative
+        refdoc = node.get('refdoc', fromdocname)
+        docname = docname_join(refdoc, node['reftarget'])
+        if docname not in env.all_docs:
+            return None
+        else:
+            if node['refexplicit']:
+                # reference with explicit title
+                caption = node.astext()
+            else:
+                caption = clean_astext(env.titles[docname])
+            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:
+        progname = node.get('std:program')
+        target = target.strip()
+        docname, labelid = self.progoptions.get((progname, target), ('', ''))
+        if not docname:
+            # Support also reference that contain an option value:
+            # * :option:`-foo=bar`
+            # * :option:`-foo[=bar]`
+            # * :option:`-foo bar`
+            for needle in {'=', '[=', ' '}:
+                if needle in target:
+                    stem, _, _ = target.partition(needle)
+                    docname, labelid = self.progoptions.get((progname, stem), ('', ''))
+                    if docname:
+                        break
+        if not docname:
+            commands = []
+            while ws_re.search(target):
+                subcommand, target = ws_re.split(target, 1)
+                commands.append(subcommand)
+                progname = "-".join(commands)
+
+                docname, labelid = self.progoptions.get((progname, target), ('', ''))
+                if docname:
+                    break
+            else:
+                return None
+
+        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)
+        if result:
+            return result
+        else:
+            # fallback to case insentive match
+            if target.lower() in self._terms:
+                docname, labelid = self._terms[target.lower()]
+                return make_refnode(builder, fromdocname, docname, labelid, contnode)
+            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:
+        objtypes = self.objtypes_for_role(typ) or []
+        for objtype in objtypes:
+            if (objtype, target) in self.objects:
+                docname, labelid = self.objects[objtype, target]
+                break
+        else:
+            docname, labelid = '', ''
+        if not docname:
+            return None
+        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]] = []
+        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)
+            if res:
+                results.append(('std:' + role, res))
+        # all others
+        for objtype in self.object_types:
+            key = (objtype, target)
+            if objtype == 'term':
+                key = (objtype, ltarget)
+            if key in self.objects:
+                docname, labelid = self.objects[key]
+                results.append(('std:' + self.role_for_objtype(objtype),
+                                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)
+        for (prog, option), info in self.progoptions.items():
+            if prog:
+                fullname = ".".join([prog, option])
+                yield (fullname, fullname, 'cmdoption', info[0], info[1], 1)
+            else:
+                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'])
+        for name, (docname, labelid, sectionname) in self.labels.items():
+            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)
+
+    def get_type_name(self, type: ObjType, primary: bool = False) -> str:
+        # never prepend "Default"
+        return type.lname
+
+    def is_enumerable_node(self, node: Node) -> bool:
+        return node.__class__ in self.enumerable_nodes
+
+    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)
+            _, title_getter = self.enumerable_nodes.get(elem.__class__, (None, None))
+            if title_getter:
+                return title_getter(elem)
+            else:
+                for subnode in elem:
+                    if isinstance(subnode, (nodes.caption, nodes.title)):
+                        return clean_astext(subnode)
+
+        return None
+
+    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)):
+            # given node is a code-block having caption
+            return 'code-block'
+        else:
+            figtype, _ = self.enumerable_nodes.get(node.__class__, (None, None))
+            return figtype
+
+    def get_fignumber(
+        self,
+        env: BuildEnvironment,
+        builder: Builder,
+        figtype: str,
+        docname: str,
+        target_node: Element
+    ) -> tuple[int, ...] | None:
+        if figtype == 'section':
+            if builder.name == 'latex':
+                return ()
+            elif docname not in env.toc_secnumbers:
+                raise ValueError  # no number assigned
+            else:
+                anchorname = '#' + target_node['ids'][0]
+                if anchorname not in env.toc_secnumbers[docname]:
+                    # try first heading which has no anchor
+                    return env.toc_secnumbers[docname].get('')
+                else:
+                    return env.toc_secnumbers[docname].get(anchorname)
+        else:
+            try:
+                figure_id = target_node['ids'][0]
+                return env.toc_fignumbers[docname][figtype][figure_id]
+            except (KeyError, IndexError) as exc:
+                # target_node is found, but fignumber is not assigned.
+                # Maybe it is defined in orphaned document.
+                raise ValueError from exc
+
+    def get_full_qualified_name(self, node: Element) -> str | None:
+        if node.get('reftype') == 'option':
+            progname = node.get('std:program')
+            command = ws_re.split(node.get('reftarget'))
+            if progname:
+                command.insert(0, progname)
+            option = command.pop()
+            if command:
+                return '.'.join(['-'.join(command), option])
+            else:
+                return None
+        else:
+            return 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:
+        target = node['reftarget']
+        if target not in domain.anonlabels:  # type: ignore
+            msg = __('undefined label: %r')
+        else:
+            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
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_domain(StandardDomain)
+    app.connect('warn-missing-reference', warn_missing_reference)
+
+    return {
+        'version': 'builtin',
+        'env_version': 2,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }