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

sphinx/directives/patches.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import os
-from os import path
-from typing import TYPE_CHECKING, ClassVar, cast
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
-from docutils.nodes import Node, make_id
+from docutils.nodes import make_id
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives import images, tables
 from docutils.parsers.rst.directives.misc import Meta
@@ -16,9 +16,13 @@ from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import set_source_info
-from sphinx.util.osutil import SEP, os_path, relpath
+from sphinx.util.osutil import SEP, relpath
 
 if TYPE_CHECKING:
+    from typing import ClassVar
+
+    from docutils.nodes import Node
+
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
@@ -38,7 +42,7 @@ class Figure(images.Figure):  # type: ignore[misc]
             return result
 
         assert len(result) == 1
-        figure_node = cast(nodes.figure, result[0])
+        figure_node = cast('nodes.figure', result[0])
         if name:
             # set ``name`` to figure_node if given
             self.options['name'] = name
@@ -46,7 +50,7 @@ class Figure(images.Figure):  # type: ignore[misc]
 
         # copy lineno from image node
         if figure_node.line is None and len(figure_node) == 2:
-            caption = cast(nodes.caption, figure_node[1])
+            caption = cast('nodes.caption', figure_node[1])
             figure_node.line = caption.line
 
         return [figure_node]
@@ -60,8 +64,8 @@ class CSVTable(tables.CSVTable):  # type: ignore[misc]
     def run(self) -> list[Node]:
         if 'file' in self.options and self.options['file'].startswith((SEP, os.sep)):
             env = self.state.document.settings.env
-            filename = self.options['file']
-            if path.exists(filename):
+            filename = Path(self.options['file'])
+            if filename.exists():
                 logger.warning(
                     __(
                         '":file:" option for csv-table directive now recognizes '
@@ -71,9 +75,9 @@ class CSVTable(tables.CSVTable):  # type: ignore[misc]
                     location=(env.docname, self.lineno),
                 )
             else:
-                abspath = path.join(env.srcdir, os_path(self.options['file'][1:]))
-                docdir = path.dirname(env.doc2path(env.docname))
-                self.options['file'] = relpath(abspath, docdir)
+                abspath = env.srcdir / self.options['file'][1:]
+                doc_dir = env.doc2path(env.docname).parent
+                self.options['file'] = relpath(abspath, doc_dir)
 
         return super().run()
 
@@ -115,8 +119,9 @@ class Code(SphinxDirective):
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            node['language'] = self.env.temp_data.get(
-                'highlight_language', self.config.highlight_language
+            node['language'] = (
+                self.env.current_document.highlight_language
+                or self.config.highlight_language
             )
 
         if 'number-lines' in self.options:
@@ -138,10 +143,17 @@ class MathDirective(SphinxDirective):
         'label': directives.unchanged,
         'name': directives.unchanged,
         'class': directives.class_option,
+        'no-wrap': directives.flag,
         'nowrap': directives.flag,
     }
 
     def run(self) -> list[Node]:
+        # Copy the old option name to the new one
+        # xref RemovedInSphinx90Warning
+        # deprecate nowrap in Sphinx 9.0
+        if 'no-wrap' not in self.options and 'nowrap' in self.options:
+            self.options['no-wrap'] = self.options['nowrap']
+
         latex = '\n'.join(self.content)
         if self.arguments and self.arguments[0]:
             latex = self.arguments[0] + '\n\n' + latex
@@ -153,8 +165,8 @@ class MathDirective(SphinxDirective):
             docname=self.env.docname,
             number=None,
             label=label,
-            nowrap='nowrap' in self.options,
         )
+        node['no-wrap'] = node['nowrap'] = 'no-wrap' in self.options
         self.add_name(node)
         self.set_source_info(node)
 
@@ -163,10 +175,10 @@ class MathDirective(SphinxDirective):
         return ret
 
     def add_target(self, ret: list[Node]) -> None:
-        node = cast(nodes.math_block, ret[0])
+        node = cast('nodes.math_block', ret[0])
 
         # assign label automatically if math_number_all enabled
-        if node['label'] == '' or (self.config.math_number_all and not node['label']):
+        if node['label'] == '' or (self.config.math_number_all and not node['label']):  # NoQA: PLC1901
             seq = self.env.new_serialno('sphinx.ext.math#equations')
             node['label'] = f'{self.env.docname}:{seq}'
 

sphinx/domains/__init__.py

@@ -13,7 +13,7 @@ from sphinx.domains._index import Index, IndexEntry
 from sphinx.locale import _
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence, Set
+    from collections.abc import Iterable, Sequence, Set
     from typing import Any
 
     from docutils import nodes
@@ -36,8 +36,7 @@ __all__ = (
 
 
 class ObjType:
-    """
-    An ObjType is the description for a type of object that a domain can
+    """An ObjType is the description for a type of object that a domain can
     document.  In the object_types attribute of Domain subclasses, object type
     names are mapped to instances of this class.
 
@@ -61,8 +60,7 @@ class ObjType:
 
 
 class Domain:
-    """
-    A Domain is meant to be a group of "object" description directives for
+    """A Domain is meant to be a group of "object" description directives for
     objects of a similar nature, and corresponding roles to create references to
     them.  Examples would be Python modules, classes, functions etc., elements
     of a templating language, Sphinx roles and directives, etc.
@@ -100,16 +98,17 @@ class Domain:
     #: node_class -> (enum_node_type, title_getter)
     enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {}
     #: data value for a fresh environment
-    initial_data: dict = {}
+    initial_data: dict[str, Any] = {}
     #: data value
     data: dict[str, Any]
     #: data version, bump this when the format of `self.data` changes
     data_version = 0
 
     def __init__(self, env: BuildEnvironment) -> None:
+        domain_data: dict[str, dict[str, Any]] = env.domaindata
         self.env: BuildEnvironment = env
-        self._role_cache: dict[str, Callable] = {}
-        self._directive_cache: dict[str, Callable] = {}
+        self._role_cache: dict[str, RoleFunction] = {}
+        self._directive_cache: dict[str, type[Directive]] = {}
         self._role2type: dict[str, list[str]] = {}
         self._type2role: dict[str, str] = {}
 
@@ -119,13 +118,13 @@ class Domain:
         self.roles = dict(self.roles)
         self.indices = list(self.indices)
 
-        if self.name not in env.domaindata:
+        if self.name not in domain_data:
             assert isinstance(self.initial_data, dict)
             new_data = copy.deepcopy(self.initial_data)
             new_data['version'] = self.data_version
-            self.data = env.domaindata[self.name] = new_data
+            self.data = domain_data[self.name] = new_data
         else:
-            self.data = env.domaindata[self.name]
+            self.data = domain_data[self.name]
             if self.data['version'] != self.data_version:
                 raise OSError('data of %r domain out of date' % self.label)
         for name, obj in self.object_types.items():
@@ -141,7 +140,7 @@ class Domain:
         std = self.env.domains.standard_domain
         for index in self.indices:
             if index.name and index.localname:
-                docname = f"{self.name}-{index.name}"
+                docname = f'{self.name}-{index.name}'
                 std.note_hyperlink_target(docname, docname, '', index.localname)
 
     def add_object_type(self, name: str, objtype: ObjType) -> None:
@@ -165,16 +164,23 @@ class Domain:
             return None
         fullname = f'{self.name}:{name}'
 
-        def role_adapter(typ: str, rawtext: str, text: str, lineno: int,
-                         inliner: Inliner, options: dict | None = None,
-                         content: Sequence[str] = (),
-                         ) -> tuple[list[Node], list[nodes.system_message]]:
-            return self.roles[name](fullname, rawtext, text, lineno,
-                                    inliner, options or {}, content)
+        def role_adapter(
+            typ: str,
+            rawtext: str,
+            text: str,
+            lineno: int,
+            inliner: Inliner,
+            options: dict[str, Any] | None = None,
+            content: Sequence[str] = (),
+        ) -> tuple[list[Node], list[nodes.system_message]]:
+            return self.roles[name](
+                fullname, rawtext, text, lineno, inliner, options or {}, content
+            )
+
         self._role_cache[name] = role_adapter
         return role_adapter
 
-    def directive(self, name: str) -> Callable | None:
+    def directive(self, name: str) -> type[Directive] | None:
         """Return a directive adapter class that always gives the registered
         directive its full name ('domain:name') as ``self.name``.
         """
@@ -189,6 +195,7 @@ class Domain:
             def run(self) -> list[Node]:
                 self.name = fullname
                 return super().run()
+
         self._directive_cache[name] = DirectiveAdapter
         return DirectiveAdapter
 
@@ -202,12 +209,15 @@ class Domain:
         """Merge in data regarding *docnames* from a different domaindata
         inventory (coming from a subprocess in parallel builds).
         """
-        raise NotImplementedError('merge_domaindata must be implemented in %s '
-                                  'to be able to do parallel builds!' %
-                                  self.__class__)
-
-    def process_doc(self, env: BuildEnvironment, docname: str,
-                    document: nodes.document) -> None:
+        msg = (
+            f'merge_domaindata must be implemented in {self.__class__} '
+            'to be able to do parallel builds!'
+        )
+        raise NotImplementedError(msg)
+
+    def process_doc(
+        self, env: BuildEnvironment, docname: str, document: nodes.document
+    ) -> None:
         """Process a document after it is read by the environment."""
         pass
 
@@ -221,9 +231,16 @@ class Domain:
         """
         pass
 
-    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:
         """Resolve the pending_xref *node* with the given *typ* and *target*.
 
         This method should return a new node, to replace the xref node,
@@ -239,9 +256,15 @@ class Domain:
         """
         pass
 
-    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
-                         target: str, node: pending_xref, contnode: Element,
-                         ) -> 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]]:
         """Resolve the pending_xref *node* with the given *target*.
 
         The reference comes from an "any" or similar role, which means that we

sphinx/domains/_domains_container.py

@@ -4,10 +4,9 @@ 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 typing import Any, Final, Literal, NoReturn, Self
 
     from docutils import nodes
-    from typing_extensions import Self
 
     from sphinx.domains import Domain
     from sphinx.domains.c import CDomain
@@ -23,6 +22,7 @@ if TYPE_CHECKING:
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.duration import DurationDomain
     from sphinx.ext.todo import TodoDomain
+    from sphinx.registry import SphinxComponentRegistry
 
 
 class _DomainsContainer:
@@ -72,8 +72,10 @@ class _DomainsContainer:
     })
 
     @classmethod
-    def _from_environment(cls, env: BuildEnvironment, /) -> Self:
-        create_domains = env.app.registry.create_domains
+    def _from_environment(
+        cls, env: BuildEnvironment, /, *, registry: SphinxComponentRegistry
+    ) -> Self:
+        create_domains = registry.create_domains
         # Initialise domains
         if domains := {domain.name: domain for domain in create_domains(env)}:
             return cls(**domains)  # type: ignore[arg-type]
@@ -188,6 +190,9 @@ class _DomainsContainer:
             return NotImplemented
         return self._domain_instances == other._domain_instances
 
+    def __hash__(self) -> int:
+        return hash(sorted(self._domain_instances.items()))
+
     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}'
@@ -203,47 +208,47 @@ class _DomainsContainer:
     # Mapping interface: builtin domains
 
     @overload
-    def __getitem__(self, key: Literal['c']) -> CDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['c']) -> CDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['cpp']) -> CPPDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['cpp']) -> CPPDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['changeset']) -> ChangeSetDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['changeset']) -> ChangeSetDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['citation']) -> CitationDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['citation']) -> CitationDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['index']) -> IndexDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['index']) -> IndexDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['js']) -> JavaScriptDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['js']) -> JavaScriptDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['math']) -> MathDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['math']) -> MathDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['py']) -> PythonDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['py']) -> PythonDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['rst']) -> ReSTDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['rst']) -> ReSTDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['std']) -> StandardDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['std']) -> StandardDomain: ...
 
     # Mapping interface: first-party domains
 
     @overload
-    def __getitem__(self, key: Literal['duration']) -> DurationDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['duration']) -> DurationDomain: ...
 
     @overload
-    def __getitem__(self, key: Literal['todo']) -> TodoDomain: ...  # NoQA: E704
+    def __getitem__(self, key: Literal['todo']) -> TodoDomain: ...
 
     # Mapping interface: third-party domains
 
     @overload
-    def __getitem__(self, key: str) -> Domain: ...  # NoQA: E704
+    def __getitem__(self, key: str) -> Domain: ...
 
     def __getitem__(self, key: str) -> Domain:
         if domain := getattr(self, key, None):

sphinx/domains/_index.py

@@ -14,8 +14,7 @@ if TYPE_CHECKING:
 
 
 class IndexEntry(NamedTuple):
-    """
-    An index entry.
+    """An index entry.
 
     .. note::
 
@@ -53,8 +52,7 @@ class IndexEntry(NamedTuple):
 
 
 class Index(ABC):
-    """
-    An Index is the description for a domain-specific index.  To add an index to
+    """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.
@@ -65,9 +63,9 @@ class Index(ABC):
     * `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
+    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()`.
+    domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain`.
 
     .. versionchanged:: 3.0
 
@@ -87,8 +85,7 @@ class Index(ABC):
 
     @abstractmethod
     def generate(
-        self,
-        docnames: Iterable[str] | None = None,
+        self, docnames: Iterable[str] | None = None
     ) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
         """Get entries for the index.