Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/domains/_domains_container.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, overload
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator, Mapping, Set
+    from typing import Any, Final, Literal, NoReturn
+
+    from docutils import nodes
+    from typing_extensions import Self
+
+    from sphinx.domains import Domain
+    from sphinx.domains.c import CDomain
+    from sphinx.domains.changeset import ChangeSetDomain
+    from sphinx.domains.citation import CitationDomain
+    from sphinx.domains.cpp import CPPDomain
+    from sphinx.domains.index import IndexDomain
+    from sphinx.domains.javascript import JavaScriptDomain
+    from sphinx.domains.math import MathDomain
+    from sphinx.domains.python import PythonDomain
+    from sphinx.domains.rst import ReSTDomain
+    from sphinx.domains.std import StandardDomain
+    from sphinx.environment import BuildEnvironment
+    from sphinx.ext.duration import DurationDomain
+    from sphinx.ext.todo import TodoDomain
+
+
+class _DomainsContainer:
+    """Container for domain instances.
+
+    This class is private, including its name, constructor, and all methods.
+    Any or all of these will change without notice or warning in any release.
+
+    The public interface is restricted to:
+
+    * the``domains.['<domain-name>']`` mapping interface
+    * the ``domains.<core-domain-name>`` attributes for core domains.
+    * the `.get()``, ``.keys()``, ``.items()``, and ``.values()`` methods.
+
+    Additionally, this class supports ``iter`` and ``len``,
+    and provides membership testing via the ``in`` operator.
+    """
+
+    __slots__ = (
+        '_domain_instances',
+        'c_domain',
+        'changeset_domain',
+        'citation_domain',
+        'cpp_domain',
+        'index_domain',
+        'javascript_domain',
+        'math_domain',
+        'python_domain',
+        'restructuredtext_domain',
+        'standard_domain',
+    )
+
+    #: First-party domains in :mod:`sphinx.domains`
+    _core_domains: Final = frozenset({
+        'std',
+        # Language-specific domains
+        'c',
+        'cpp',
+        'js',
+        'py',
+        'rst',
+        # Other core domains
+        'changeset',
+        'citation',
+        'index',
+        'math',
+    })
+
+    @classmethod
+    def _from_environment(cls, env: BuildEnvironment, /) -> Self:
+        create_domains = env.app.registry.create_domains
+        # Initialise domains
+        if domains := {domain.name: domain for domain in create_domains(env)}:
+            return cls(**domains)  # type: ignore[arg-type]
+
+        return cls._from_environment_default(env=env)
+
+    @classmethod
+    def _from_environment_default(cls, *, env: BuildEnvironment) -> Self:
+        """Return a default instance with every domain we require."""
+        from sphinx.domains.c import CDomain
+        from sphinx.domains.changeset import ChangeSetDomain
+        from sphinx.domains.citation import CitationDomain
+        from sphinx.domains.cpp import CPPDomain
+        from sphinx.domains.index import IndexDomain
+        from sphinx.domains.javascript import JavaScriptDomain
+        from sphinx.domains.math import MathDomain
+        from sphinx.domains.python import PythonDomain
+        from sphinx.domains.rst import ReSTDomain
+        from sphinx.domains.std import StandardDomain
+
+        return cls(
+            c=CDomain(env),
+            changeset=ChangeSetDomain(env),
+            citation=CitationDomain(env),
+            cpp=CPPDomain(env),
+            index=IndexDomain(env),
+            js=JavaScriptDomain(env),
+            math=MathDomain(env),
+            py=PythonDomain(env),
+            rst=ReSTDomain(env),
+            std=StandardDomain(env),
+        )
+
+    def __init__(
+        self,
+        *,
+        c: CDomain,
+        cpp: CPPDomain,
+        js: JavaScriptDomain,
+        py: PythonDomain,
+        rst: ReSTDomain,
+        std: StandardDomain,
+        changeset: ChangeSetDomain,
+        citation: CitationDomain,
+        index: IndexDomain,
+        math: MathDomain,
+        **domains: Domain,
+    ) -> None:
+        # All domains, including core.
+        # Implemented as a dict for backwards compatibility.
+        self._domain_instances: Mapping[str, Domain] = {
+            'c': c,
+            'changeset': changeset,
+            'citation': citation,
+            'cpp': cpp,
+            'index': index,
+            'js': js,
+            'math': math,
+            'py': py,
+            'rst': rst,
+            'std': std,
+            **domains,
+        }
+
+        # Provide typed attributes for the core domains
+        self.standard_domain: StandardDomain = std
+        self.c_domain: CDomain = c
+        self.cpp_domain: CPPDomain = cpp
+        self.javascript_domain: JavaScriptDomain = js
+        self.python_domain: PythonDomain = py
+        self.restructuredtext_domain: ReSTDomain = rst
+        self.changeset_domain: ChangeSetDomain = changeset
+        self.citation_domain: CitationDomain = citation
+        self.index_domain: IndexDomain = index
+        self.math_domain: MathDomain = math
+
+        for domain_name, domain in self._domain_instances.items():
+            # invariant from ``_DomainsContainer._from_environment``
+            if domain_name != domain.name:
+                msg = f'Domain name mismatch in {domain!r}: {domain_name!r} != {domain.name!r}'
+                raise ValueError(msg)
+
+    def _setup(self) -> None:
+        for domain in self._domain_instances.values():
+            domain.setup()
+
+    def _process_doc(
+        self, env: BuildEnvironment, docname: str, document: nodes.document
+    ) -> None:
+        for domain in self._domain_instances.values():
+            domain.process_doc(env, docname, document)
+
+    def _clear_doc(self, docname: str) -> None:
+        for domain in self._domain_instances.values():
+            domain.clear_doc(docname)
+
+    def _merge_domain_data(
+        self, docnames: Set[str], domain_data: dict[str, Any]
+    ) -> None:
+        for domain_name, domain in self._domain_instances.items():
+            domain.merge_domaindata(docnames, domain_data[domain_name])
+
+    def _check_consistency(self) -> None:
+        for domain in self._domain_instances.values():
+            domain.check_consistency()
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._domain_instances
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _DomainsContainer):
+            return NotImplemented
+        return self._domain_instances == other._domain_instances
+
+    def __setattr__(self, key: str, value: object) -> None:
+        if key in self._core_domains:
+            msg = f'{self.__class__.__name__!r} object does not support assignment to {key!r}'
+            raise TypeError(msg)
+        super().__setattr__(key, value)
+
+    def __delattr__(self, key: str) -> None:
+        if key in self._core_domains:
+            msg = f'{self.__class__.__name__!r} object does not support deletion of {key!r}'
+            raise TypeError(msg)
+        super().__delattr__(key)
+
+    # Mapping interface: builtin domains
+
+    @overload
+    def __getitem__(self, key: Literal['c']) -> CDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['cpp']) -> CPPDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['changeset']) -> ChangeSetDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['citation']) -> CitationDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['index']) -> IndexDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['js']) -> JavaScriptDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['math']) -> MathDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['py']) -> PythonDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['rst']) -> ReSTDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['std']) -> StandardDomain: ...  # NoQA: E704
+
+    # Mapping interface: first-party domains
+
+    @overload
+    def __getitem__(self, key: Literal['duration']) -> DurationDomain: ...  # NoQA: E704
+
+    @overload
+    def __getitem__(self, key: Literal['todo']) -> TodoDomain: ...  # NoQA: E704
+
+    # Mapping interface: third-party domains
+
+    @overload
+    def __getitem__(self, key: str) -> Domain: ...  # NoQA: E704
+
+    def __getitem__(self, key: str) -> Domain:
+        if domain := getattr(self, key, None):
+            return domain
+        return self._domain_instances[key]
+
+    def __setitem__(self, key: str, value: Domain) -> NoReturn:
+        msg = f'{self.__class__.__name__!r} object does not support item assignment'
+        raise TypeError(msg)
+
+    def __delitem__(self, key: str) -> NoReturn:
+        msg = f'{self.__class__.__name__!r} object does not support item deletion'
+        raise TypeError(msg)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._domain_instances.keys())
+
+    def __len__(self) -> int:
+        return len(self._domain_instances)
+
+    def get(self, key: str, default: Domain | None = None) -> Domain | None:
+        return self._domain_instances.get(key, default)
+
+    def keys(self) -> Iterable[str]:
+        return self._domain_instances.keys()
+
+    def items(self) -> Iterable[tuple[str, Domain]]:
+        return self._domain_instances.items()
+
+    def values(self) -> Iterable[Domain]:
+        return self._domain_instances.values()
+
+    def sorted(self) -> Iterable[Domain]:
+        for _domain_name, domain in sorted(self._domain_instances.items()):
+            yield domain

sphinx/domains/_index.py

@@ -0,0 +1,110 @@
+"""Domain indices."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, NamedTuple
+
+from sphinx.errors import SphinxError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from sphinx.domains import Domain
+
+
+class IndexEntry(NamedTuple):
+    """
+    An index entry.
+
+    .. note::
+
+       The *qualifier* and *description* are not rendered for some output formats,
+       such as LaTeX.
+    """
+
+    #: The name of the index entry to be displayed.
+    name: str
+
+    #: The sub-entry related type. One of:
+    #:
+    #: ``0``
+    #:   A normal entry.
+    #: ``1``
+    #:   An entry with sub-entries.
+    #: ``2``
+    #:   A sub-entry.
+    subtype: int
+
+    #: *docname* where the entry is located.
+    docname: str
+
+    #: Anchor for the entry within `docname`
+    anchor: str
+
+    #: Extra info for the entry.
+    extra: str
+
+    #: Qualifier for the description.
+    qualifier: str
+
+    #: Description for the entry.
+    descr: str
+
+
+class Index(ABC):
+    """
+    An Index is the description for a domain-specific index.  To add an index to
+    a domain, subclass Index, overriding the three name attributes:
+
+    * `name` is an identifier used for generating file names.
+      It is also used for a hyperlink target for the index. Therefore, users can
+      refer the index page using ``ref`` role and a string which is combined
+      domain name and ``name`` attribute (ex. ``:ref:`py-modindex```).
+    * `localname` is the section title for the index.
+    * `shortname` is a short name for the index, for use in the relation bar in
+      HTML output.  Can be empty to disable entries in the relation bar.
+
+    and providing a :meth:`generate()` method.  Then, add the index class to
+    your domain's `indices` list.  Extensions can add indices to existing
+    domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`.
+
+    .. versionchanged:: 3.0
+
+       Index pages can be referred by domain name and index name via
+       :rst:role:`ref` role.
+    """
+
+    name: str
+    localname: str
+    shortname: str | None = None
+
+    def __init__(self, domain: Domain) -> None:
+        if not self.name or self.localname is None:
+            msg = f'Index subclass {self.__class__.__name__} has no valid name or localname'
+            raise SphinxError(msg)
+        self.domain = domain
+
+    @abstractmethod
+    def generate(
+        self,
+        docnames: Iterable[str] | None = None,
+    ) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
+        """Get entries for the index.
+
+        If ``docnames`` is given, restrict to entries referring to these
+        docnames.
+
+        The return value is a tuple of ``(content, collapse)``:
+
+        ``collapse``
+          A boolean that determines if sub-entries should start collapsed (for
+          output formats that support collapsing sub-entries).
+
+        ``content``:
+          A sequence of ``(letter, entries)`` tuples, where ``letter`` is the
+          "heading" for the given ``entries``, usually the starting letter, and
+          ``entries`` is a sequence of single entries.
+          Each entry is an :py:class:`IndexEntry`.
+        """
+        raise NotImplementedError

sphinx/domains/c/__init__.py

@@ -33,7 +33,7 @@ from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
     from docutils.nodes import Element, Node, TextElement, system_message
 
@@ -526,7 +526,7 @@ class AliasTransform(SphinxTransform):
                 node.replace_self(signode)
                 continue
 
-            rootSymbol: Symbol = self.env.domains['c'].data['root_symbol']
+            rootSymbol: Symbol = self.env.domains.c_domain.data['root_symbol']
             parentSymbol: Symbol | None = rootSymbol.direct_lookup(parentKey)
             if not parentSymbol:
                 logger.debug("Target: %s", sig)
@@ -745,7 +745,7 @@ class CDomain(Domain):
     def process_field_xref(self, pnode: pending_xref) -> None:
         pnode.attributes.update(self.env.ref_context)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         if Symbol.debug_show_tree:
             logger.debug("merge_domaindata:")
             logger.debug("\tself:")

sphinx/domains/c/_parser.py

@@ -495,9 +495,11 @@ class DefinitionParser(BaseParser):
                 self.fail("Expected identifier in nested name, "
                           "got keyword: %s" % identifier)
             if self.matched_text in self.config.c_extra_keywords:
-                msg = "Expected identifier, got user-defined keyword: %s." \
-                      + " Remove it from c_extra_keywords to allow it as identifier.\n" \
-                      + "Currently c_extra_keywords is %s."
+                msg = (
+                    'Expected identifier, got user-defined keyword: %s.'
+                    ' Remove it from c_extra_keywords to allow it as identifier.\n'
+                    'Currently c_extra_keywords is %s.'
+                )
                 self.fail(msg % (self.matched_text,
                                  str(self.config.c_extra_keywords)))
             ident = ASTIdentifier(identifier)
@@ -670,9 +672,11 @@ class DefinitionParser(BaseParser):
                     self.fail("Expected identifier, "
                               "got keyword: %s" % self.matched_text)
                 if self.matched_text in self.config.c_extra_keywords:
-                    msg = "Expected identifier, got user-defined keyword: %s." \
-                          + " Remove it from c_extra_keywords to allow it as identifier.\n" \
-                          + "Currently c_extra_keywords is %s."
+                    msg = (
+                        'Expected identifier, got user-defined keyword: %s. '
+                        'Remove it from c_extra_keywords to allow it as identifier.\n'
+                        'Currently c_extra_keywords is %s.'
+                    )
                     self.fail(msg % (self.matched_text,
                                      str(self.config.c_extra_keywords)))
                 identifier = ASTIdentifier(self.matched_text)

sphinx/domains/changeset.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, cast
+from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple
 
 from docutils import nodes
 
@@ -12,6 +12,8 @@ from sphinx.locale import _
 from sphinx.util.docutils import SphinxDirective
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -96,7 +98,7 @@ class VersionChange(SphinxDirective):
                                    translatable=False)
             node.append(para)
 
-        domain = cast(ChangeSetDomain, self.env.get_domain('changeset'))
+        domain = self.env.domains.changeset_domain
         domain.note_changeset(node)
 
         ret: list[Node] = [node]
@@ -132,7 +134,7 @@ class ChangeSetDomain(Domain):
                 if changeset.docname == docname:
                     changes.remove(changeset)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         # XXX duplicates?
         for version, otherchanges in otherdata['changes'].items():
             changes = self.changesets.setdefault(version, [])

sphinx/domains/citation.py

@@ -14,6 +14,8 @@ from sphinx.util import logging
 from sphinx.util.nodes import copy_source_info, make_refnode
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils.nodes import Element
 
     from sphinx.application import Sphinx
@@ -53,7 +55,7 @@ class CitationDomain(Domain):
             elif docname in docnames:
                 docnames.remove(docname)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         # XXX duplicates?
         for key, data in otherdata['citations'].items():
             if data[0] in docnames:
@@ -108,7 +110,7 @@ class CitationDefinitionTransform(SphinxTransform):
     default_priority = 619
 
     def apply(self, **kwargs: Any) -> None:
-        domain = cast(CitationDomain, self.env.get_domain('citation'))
+        domain = self.env.domains.citation_domain
         for node in self.document.findall(nodes.citation):
             # register citation node to domain
             node['docname'] = self.env.docname
@@ -128,7 +130,7 @@ class CitationReferenceTransform(SphinxTransform):
     default_priority = 619
 
     def apply(self, **kwargs: Any) -> None:
-        domain = cast(CitationDomain, self.env.get_domain('citation'))
+        domain = self.env.domains.citation_domain
         for node in self.document.findall(nodes.citation_reference):
             target = node.astext()
             ref = pending_xref(target, refdomain='citation', reftype='ref',

sphinx/domains/cpp/__init__.py

@@ -37,7 +37,7 @@ from sphinx.util.docutils import SphinxDirective, SphinxRole
 from sphinx.util.nodes import make_refnode
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Set
 
     from docutils.nodes import Element, Node, TextElement, system_message
 
@@ -661,7 +661,7 @@ class AliasTransform(SphinxTransform):
                 node.replace_self(signode)
                 continue
 
-            rootSymbol: Symbol = self.env.domains['cpp'].data['root_symbol']
+            rootSymbol: Symbol = self.env.domains.cpp_domain.data['root_symbol']
             parentSymbol: Symbol = rootSymbol.direct_lookup(parentKey)
             if not parentSymbol:
                 logger.debug("Target: %s", sig)
@@ -784,10 +784,9 @@ class CPPXRefRole(XRefRole):
         if refnode['reftype'] == 'any':
             # Assume the removal part of fix_parens for :any: refs.
             # The addition part is done with the reference is resolved.
-            if not has_explicit_title and title.endswith('()'):
-                title = title[:-2]
-            if target.endswith('()'):
-                target = target[:-2]
+            if not has_explicit_title:
+                title = title.removesuffix('()')
+            target = target.removesuffix('()')
         # TODO: should this really be here?
         if not has_explicit_title:
             target = target.lstrip('~')  # only has a meaning for the title
@@ -934,7 +933,7 @@ class CPPDomain(Domain):
     def process_field_xref(self, pnode: pending_xref) -> None:
         pnode.attributes.update(self.env.ref_context)
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         if Symbol.debug_show_tree:
             logger.debug("merge_domaindata:")
             logger.debug("\tself:")
@@ -1036,8 +1035,7 @@ class CPPDomain(Domain):
                 raise NoUri(txtName, typ)
             return None, None
 
-        if typ.startswith('cpp:'):
-            typ = typ[4:]
+        typ = typ.removeprefix('cpp:')
         declTyp = s.declaration.objectType
 
         def checkType() -> bool:
@@ -1093,8 +1091,8 @@ class CPPDomain(Domain):
                         if typ == 'any' and displayName.endswith('()'):
                             addParen += 1
                         elif typ == 'func':
-                            if title.endswith('()') and not displayName.endswith('()'):
-                                title = title[:-2]
+                            if not displayName.endswith('()'):
+                                title = title.removesuffix('()')
                     else:
                         if displayName.endswith('()'):
                             addParen += 1

sphinx/domains/cpp/_parser.py

@@ -1263,7 +1263,7 @@ class DefinitionParser(BaseParser):
                         if self.skip_string('('):
                             expr = self._parse_constant_expression(inTemplate=False)
                             if not expr:
-                                self.fail("Expected constant expression after '('" +
+                                self.fail("Expected constant expression after '('"
                                           " in explicit specifier.")
                             self.skip_ws()
                             if not self.skip_string(')'):
@@ -1972,13 +1972,14 @@ class DefinitionParser(BaseParser):
         if numArgs > numParams:
             numExtra = numArgs - numParams
             if not fullSpecShorthand and not isMemberInstantiation:
-                msg = "Too many template argument lists compared to parameter" \
-                    " lists. Argument lists: %d, Parameter lists: %d," \
-                    " Extra empty parameters lists prepended: %d." \
-                    % (numArgs, numParams, numExtra)
-                msg += " Declaration:\n\t"
+                msg = (
+                    f'Too many template argument lists compared to parameter lists. '
+                    f'Argument lists: {numArgs:d}, Parameter lists: {numParams:d}, '
+                    f'Extra empty parameters lists prepended: {numExtra:d}. '
+                    'Declaration:\n\t'
+                )
                 if templatePrefix:
-                    msg += "%s\n\t" % templatePrefix
+                    msg += f"{templatePrefix}\n\t"
                 msg += str(nestedName)
                 self.warn(msg)
 

sphinx/domains/index.py

@@ -15,7 +15,7 @@ from sphinx.util.index_entries import split_index_msg
 from sphinx.util.nodes import process_index_entry
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Set
 
     from docutils.nodes import Node, system_message
 
@@ -28,7 +28,7 @@ logger = logging.getLogger(__name__)
 
 
 class IndexDomain(Domain):
-    """Mathematics domain."""
+    """Index domain."""
 
     name = 'index'
     label = 'index'
@@ -40,7 +40,7 @@ class IndexDomain(Domain):
     def clear_doc(self, docname: str) -> None:
         self.entries.pop(docname, None)
 
-    def merge_domaindata(self, docnames: Iterable[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         for docname in docnames:
             self.entries[docname] = otherdata['entries'][docname]