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

sphinx/directives/__init__.py

@@ -3,22 +3,25 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, ClassVar, Generic, TypeVar, cast
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
-from sphinx.addnodes import desc_signature  # NoQA: TCH001
 from sphinx.util import docutils
-from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
+from sphinx.util.docfields import DocFieldTransformer
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.typing import ExtensionMetadata, OptionSpec  # NoQA: TCH001
 
 if TYPE_CHECKING:
+    from typing import ClassVar
+
     from docutils.nodes import Node
 
+    from sphinx.addnodes import desc_signature
     from sphinx.application import Sphinx
+    from sphinx.util.docfields import Field, TypedField
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 
 # RE to strip backslash escapes
@@ -27,9 +30,7 @@ strip_backslash_re = re.compile(r'\\(.)')
 
 
 def optional_int(argument: str) -> int | None:
-    """
-    Check for an integer argument or None value; raise ``ValueError`` if not.
-    """
+    """Check for an integer argument or None value; raise ``ValueError`` if not."""
     if argument is None:
         return None
     else:
@@ -44,10 +45,10 @@ ObjDescT = TypeVar('ObjDescT')
 
 
 class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
-    """
-    Directive to describe a class, function or similar object.  Not used
-    directly, but subclassed (in domain-specific directives) to add custom
-    behavior.
+    """Directive to describe a class, function or similar object.
+
+    Not used directly, but subclassed (in domain-specific directives)
+    to add custom behaviour.
     """
 
     has_content = True
@@ -81,16 +82,16 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
                     self._doc_field_type_map[name] = (field, False)
 
                 if field.is_typed:
-                    typed_field = cast(TypedField, field)
+                    typed_field = cast('TypedField', field)
                     for name in typed_field.typenames:
                         self._doc_field_type_map[name] = (field, True)
 
         return self._doc_field_type_map
 
     def get_signatures(self) -> list[str]:
-        """
-        Retrieve the signatures to document from the directive arguments.  By
-        default, signatures are given as arguments, one per line.
+        """Retrieve the signatures to document from the directive arguments.
+
+        By default, signatures are given as arguments, one per line.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -100,9 +101,10 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
             return [line.strip() for line in lines]
 
     def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
-        """
-        Parse the signature *sig* into individual nodes and append them to
-        *signode*. If ValueError is raised, parsing is aborted and the whole
+        """Parse the signature *sig*.
+
+        The individual nodes are then appended to *signode*.
+        If ValueError is raised, parsing is aborted and the whole
         *sig* is put into a single desc_name node.
 
         The return value should be a value that identifies the object.  It is
@@ -114,39 +116,39 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     def add_target_and_index(
         self, name: ObjDescT, sig: str, signode: desc_signature
     ) -> None:
-        """
-        Add cross-reference IDs and entries to self.indexnode, if applicable.
+        """Add cross-reference IDs and entries to self.indexnode, if applicable.
 
         *name* is whatever :meth:`handle_signature()` returned.
         """
         pass  # do nothing by default
 
     def before_content(self) -> None:
-        """
-        Called before parsing content. Used to set information about the current
-        directive context on the build environment.
+        """Called before parsing content.
+
+        Used to set information about the current directive context
+        on the build environment.
         """
         pass
 
     def transform_content(self, content_node: addnodes.desc_content) -> None:
-        """
+        """Can be used to manipulate the content.
+
         Called after creating the content through nested parsing,
         but before the ``object-description-transform`` event is emitted,
         and before the info-fields are transformed.
-        Can be used to manipulate the content.
         """
         pass
 
     def after_content(self) -> None:
-        """
-        Called after parsing content. Used to reset information about the
-        current directive context on the build environment.
+        """Called after parsing content.
+
+        Used to reset information about the current directive context
+        on the build environment.
         """
         pass
 
     def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
-        """
-        Returns a tuple of strings, one entry for each part of the object's
+        """Returns a tuple of strings, one entry for each part of the object's
         hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
         returned tuple is used to properly nest children within parents in the
         table of contents, and can also be used within the
@@ -157,8 +159,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         return ()
 
     def _toc_entry_name(self, sig_node: desc_signature) -> str:
-        """
-        Returns the text of the table of contents entry for the object.
+        """Returns the text of the table of contents entry for the object.
 
         This function is called once, in :py:meth:`run`, to set the name for the
         table of contents entry (a special attribute ``_toc_name`` is set on the
@@ -183,8 +184,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         return ''
 
     def run(self) -> list[Node]:
-        """
-        Main directive entry function, called by docutils upon encountering the
+        """Main directive entry function, called by docutils upon encountering the
         directive.
 
         This directive is meant to be quite easily subclassable, so it delegates
@@ -267,7 +267,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
             finally:
                 # Private attributes for ToC generation. Will be modified or removed
                 # without notice.
-                if self.env.app.config.toc_object_entries:
+                if self.config.toc_object_entries:
                     signode['_toc_parts'] = self._object_hierarchy_parts(signode)
                     signode['_toc_name'] = self._toc_entry_name(signode)
                 else:
@@ -282,17 +282,21 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
 
         if self.names:
             # needed for association of version{added,changed} directives
-            self.env.temp_data['object'] = self.names[0]
+            object_name: ObjDescT = self.names[0]
+            if isinstance(object_name, tuple):
+                self.env.current_document.obj_desc_name = str(object_name[0])
+            else:
+                self.env.current_document.obj_desc_name = str(object_name)
         self.before_content()
         content_children = self.parse_content_to_nodes(allow_section_headings=True)
         content_node = addnodes.desc_content('', *content_children)
         node.append(content_node)
         self.transform_content(content_node)
-        self.env.app.emit(
+        self.env.events.emit(
             'object-description-transform', self.domain, self.objtype, content_node
         )
         DocFieldTransformer(self).transform_all(content_node)
-        self.env.temp_data['object'] = None
+        self.env.current_document.obj_desc_name = ''
         self.after_content()
 
         if node['no-typesetting']:
@@ -314,9 +318,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
 
 
 class DefaultRole(SphinxDirective):
-    """
-    Set the default interpreted text role.  Overridden from docutils.
-    """
+    """Set the default interpreted text role.  Overridden from docutils."""
 
     optional_arguments = 1
     final_argument_whitespace = False
@@ -331,7 +333,7 @@ class DefaultRole(SphinxDirective):
         )
         if role:
             docutils.register_role('', role)  # type: ignore[arg-type]
-            self.env.temp_data['default_role'] = role_name
+            self.env.current_document.default_role = role_name
         else:
             literal_block = nodes.literal_block(self.block_text, self.block_text)
             reporter = self.state.reporter
@@ -342,13 +344,11 @@ class DefaultRole(SphinxDirective):
             )
             messages += [error]
 
-        return cast(list[nodes.Node], messages)
+        return cast('list[nodes.Node]', messages)
 
 
 class DefaultDomain(SphinxDirective):
-    """
-    Directive to (re-)set the default domain for this source file.
-    """
+    """Directive to (re-)set the default domain for this source file."""
 
     has_content = False
     required_arguments = 1
@@ -358,18 +358,15 @@ class DefaultDomain(SphinxDirective):
 
     def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
-        # if domain_name not in env.domains:
-        #     # try searching by label
-        #     for domain in env.domains.sorted():
-        #         if domain.label.lower() == domain_name:
-        #             domain_name = domain.name
-        #             break
-        self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
+        default_domain = self.env.domains.get(domain_name)
+        self.env.current_document.default_domain = default_domain
         return []
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value('strip_signature_backslash', False, 'env')
+    app.add_config_value(
+        'strip_signature_backslash', False, 'env', types=frozenset({bool})
+    )
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
     directives.register_directive('describe', ObjectDescription)

sphinx/directives/admonitions.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+
+from sphinx import addnodes
+from sphinx.util.docutils import SphinxDirective
+
+if TYPE_CHECKING:
+    from typing import ClassVar
+
+    from docutils.nodes import Node
+
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata, OptionSpec
+
+
+def _collapsible_arg(argument: str | None) -> str:
+    if argument is None:
+        return 'open'
+    if (value := argument.lower().strip()) in {'open', 'closed'}:
+        return value
+    msg = f'"{argument}" unknown; choose from "open" or "closed".'
+    raise ValueError(msg)
+
+
+class SphinxAdmonition(BaseAdmonition, SphinxDirective):
+    option_spec: ClassVar[OptionSpec] = BaseAdmonition.option_spec.copy()  # type: ignore[union-attr]
+    option_spec |= {
+        'collapsible': _collapsible_arg,
+    }
+
+    node_class: type[nodes.Admonition] = nodes.admonition
+    """Subclasses must set this to the appropriate admonition node class."""
+
+    def run(self) -> list[Node]:
+        (admonition_node,) = super().run()
+        return [admonition_node]
+
+
+class Admonition(SphinxAdmonition):
+    required_arguments = 1
+    node_class = nodes.admonition
+
+
+class Attention(SphinxAdmonition):
+    node_class = nodes.attention
+
+
+class Caution(SphinxAdmonition):
+    node_class = nodes.caution
+
+
+class Danger(SphinxAdmonition):
+    node_class = nodes.danger
+
+
+class Error(SphinxAdmonition):
+    node_class = nodes.error
+
+
+class Hint(SphinxAdmonition):
+    node_class = nodes.hint
+
+
+class Important(SphinxAdmonition):
+    node_class = nodes.important
+
+
+class Note(SphinxAdmonition):
+    node_class = nodes.note
+
+
+class Tip(SphinxAdmonition):
+    node_class = nodes.tip
+
+
+class Warning(SphinxAdmonition):
+    node_class = nodes.warning
+
+
+class SeeAlso(SphinxAdmonition):
+    """An admonition mentioning things to look at as reference."""
+
+    node_class = addnodes.seealso
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_directive('admonition', Admonition, override=True)
+    app.add_directive('attention', Attention, override=True)
+    app.add_directive('caution', Caution, override=True)
+    app.add_directive('danger', Danger, override=True)
+    app.add_directive('error', Error, override=True)
+    app.add_directive('hint', Hint, override=True)
+    app.add_directive('important', Important, override=True)
+    app.add_directive('note', Note, override=True)
+    app.add_directive('tip', Tip, override=True)
+    app.add_directive('warning', Warning, override=True)
+    app.add_directive('seealso', SeeAlso, override=True)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinx/directives/code.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import sys
 import textwrap
 from difflib import unified_diff
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -13,9 +13,13 @@ from sphinx.directives import optional_int
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util._lines import parse_line_num_spec
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.docutils import SphinxDirective
 
 if TYPE_CHECKING:
+    import os
+    from typing import Any, ClassVar
+
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
@@ -26,8 +30,7 @@ logger = logging.getLogger(__name__)
 
 
 class Highlight(SphinxDirective):
-    """
-    Directive to set the highlighting language for code blocks, as well
+    """Directive to set the highlighting language for code blocks, as well
     as the threshold for line numbers.
     """
 
@@ -45,7 +48,7 @@ class Highlight(SphinxDirective):
         linenothreshold = self.options.get('linenothreshold', sys.maxsize)
         force = 'force' in self.options
 
-        self.env.temp_data['highlight_language'] = language
+        self.env.current_document.highlight_language = language
         return [
             addnodes.highlightlang(
                 lang=language, force=force, linenothreshold=linenothreshold
@@ -82,7 +85,7 @@ def container_wrapper(
     node = parsed[0]
     if isinstance(node, nodes.system_message):
         msg = __('Invalid caption: %s') % node.astext()
-        raise ValueError(msg)
+        raise ValueError(msg)  # NoQA: TRY004
     if isinstance(node, nodes.Element):
         caption_node = nodes.caption(node.rawsource, '', *node.children)
         caption_node.source = literal_node.source
@@ -94,8 +97,7 @@ def container_wrapper(
 
 
 class CodeBlock(SphinxDirective):
-    """
-    Directive for a code block with special highlighting or line numbering
+    """Directive for a code block with special highlighting or line numbering
     settings.
     """
 
@@ -156,8 +158,9 @@ class CodeBlock(SphinxDirective):
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            literal['language'] = self.env.temp_data.get(
-                'highlight_language', self.config.highlight_language
+            literal['language'] = (
+                self.env.current_document.highlight_language
+                or self.config.highlight_language
             )
         extra_args = literal['highlight_args'] = {}
         if hl_lines is not None:
@@ -197,8 +200,10 @@ class LiteralIncludeReader:
         ('diff', 'end-at'),
     ]
 
-    def __init__(self, filename: str, options: dict[str, Any], config: Config) -> None:
-        self.filename = filename
+    def __init__(
+        self, filename: str | os.PathLike[str], options: dict[str, Any], config: Config
+    ) -> None:
+        self.filename = _StrPath(filename)
         self.options = options
         self.encoding = options.get('encoding', config.source_encoding)
         self.lineno_start = self.options.get('lineno-start', 1)
@@ -212,21 +217,22 @@ class LiteralIncludeReader:
                 raise ValueError(msg)
 
     def read_file(
-        self, filename: str, location: tuple[str, int] | None = None
+        self, filename: str | os.PathLike[str], location: tuple[str, int] | None = None
     ) -> list[str]:
+        filename = _StrPath(filename)
         try:
             with open(filename, encoding=self.encoding, errors='strict') as f:
                 text = f.read()
-                if 'tab-width' in self.options:
-                    text = text.expandtabs(self.options['tab-width'])
+            if 'tab-width' in self.options:
+                text = text.expandtabs(self.options['tab-width'])
 
-                return text.splitlines(True)
+            return text.splitlines(True)
         except OSError as exc:
-            msg = __('Include file %r not found or reading it failed') % filename
+            msg = __("Include file '%s' not found or reading it failed") % filename
             raise OSError(msg) from exc
         except UnicodeError as exc:
             msg = __(
-                'Encoding %r used for reading included file %r seems to '
+                "Encoding %r used for reading included file '%s' seems to "
                 'be wrong, try giving an :encoding: option'
             ) % (self.encoding, filename)
             raise UnicodeError(msg) from exc
@@ -403,8 +409,7 @@ class LiteralIncludeReader:
 
 
 class LiteralInclude(SphinxDirective):
-    """
-    Like ``.. include:: :literal:``, but only warns if the include file is
+    """Like ``.. include:: :literal:``, but only warns if the include file is
     not found, and does not raise errors.  Also has several options for
     selecting what to include.
     """

sphinx/directives/other.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
 
 import re
-from os.path import abspath, relpath
+from os.path import relpath
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, ClassVar, cast
+from typing import TYPE_CHECKING, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from docutils.parsers.rst.directives.admonitions import BaseAdmonition
 from docutils.parsers.rst.directives.misc import Class
 from docutils.parsers.rst.directives.misc import Include as BaseInclude
 from docutils.statemachine import StateMachine
@@ -22,6 +21,7 @@ from sphinx.util.nodes import explicit_title_re
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Any, ClassVar
 
     from docutils.nodes import Element, Node
 
@@ -40,8 +40,7 @@ def int_or_nothing(argument: str) -> int:
 
 
 class TocTree(SphinxDirective):
-    """
-    Directive to notify Sphinx about the hierarchical structure of the docs,
+    """Directive to notify Sphinx about the hierarchical structure of the docs,
     and to include a table-of-contents like tree in the current document.
     """
 
@@ -88,9 +87,7 @@ class TocTree(SphinxDirective):
         return [wrappernode]
 
     def parse_content(self, toctree: addnodes.toctree) -> None:
-        """
-        Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content.
-        """
+        """Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content."""
         generated_docnames = frozenset(StandardDomain._virtual_doc_names)
         suffixes = self.config.source_suffix
         current_docname = self.env.docname
@@ -122,6 +119,7 @@ class TocTree(SphinxDirective):
                         __("toctree glob pattern %r didn't match any documents"),
                         entry,
                         location=toctree,
+                        subtype='empty_glob',
                     )
 
                 for docname in doc_names:
@@ -159,7 +157,7 @@ class TocTree(SphinxDirective):
                     subtype = 'not_readable'
 
                 logger.warning(
-                    msg, docname, type='toc', subtype=subtype, location=toctree
+                    msg, docname, location=toctree, type='toc', subtype=subtype
                 )
                 self.env.note_reread()
                 continue
@@ -171,6 +169,8 @@ class TocTree(SphinxDirective):
                     __('duplicated entry found in toctree: %s'),
                     docname,
                     location=toctree,
+                    type='toc',
+                    subtype='duplicate_entry',
                 )
 
             toctree['entries'].append((title, docname))
@@ -183,8 +183,7 @@ class TocTree(SphinxDirective):
 
 
 class Author(SphinxDirective):
-    """
-    Directive to give the name of the author of the current document
+    """Directive to give the name of the author of the current document
     or section. Shown in the output only if the show_authors option is on.
     """
 
@@ -217,18 +216,8 @@ class Author(SphinxDirective):
         return ret
 
 
-class SeeAlso(BaseAdmonition):
-    """
-    An admonition mentioning things to look at as reference.
-    """
-
-    node_class = addnodes.seealso
-
-
 class TabularColumns(SphinxDirective):
-    """
-    Directive to give an explicit tabulary column definition to LaTeX.
-    """
+    """Directive to give an explicit tabulary column definition to LaTeX."""
 
     has_content = False
     required_arguments = 1
@@ -244,9 +233,7 @@ class TabularColumns(SphinxDirective):
 
 
 class Centered(SphinxDirective):
-    """
-    Directive to create a centered line of bold text.
-    """
+    """Directive to create a centered line of bold text."""
 
     has_content = False
     required_arguments = 1
@@ -267,9 +254,7 @@ class Centered(SphinxDirective):
 
 
 class Acks(SphinxDirective):
-    """
-    Directive for a list of names.
-    """
+    """Directive for a list of names."""
 
     has_content = True
     required_arguments = 0
@@ -289,9 +274,7 @@ class Acks(SphinxDirective):
 
 
 class HList(SphinxDirective):
-    """
-    Directive for a list that gets compacted horizontally.
-    """
+    """Directive for a list that gets compacted horizontally."""
 
     has_content = True
     required_arguments = 0
@@ -326,9 +309,7 @@ class HList(SphinxDirective):
 
 
 class Only(SphinxDirective):
-    """
-    Directive to only include text if the given tag(s) are enabled.
-    """
+    """Directive to only include text if the given tag(s) are enabled."""
 
     has_content = True
     required_arguments = 1
@@ -376,7 +357,7 @@ class Only(SphinxDirective):
             # Use these depths to determine where the nested sections should
             # be placed in the doctree.
             n_sects_to_raise = current_depth - nested_depth + 1
-            parent = cast(nodes.Element, self.state.parent)
+            parent = cast('nodes.Element', self.state.parent)
             for _i in range(n_sects_to_raise):
                 if parent.parent:
                     parent = parent.parent
@@ -388,8 +369,7 @@ class Only(SphinxDirective):
 
 
 class Include(BaseInclude, SphinxDirective):
-    """
-    Like the standard "Include" directive, but interprets absolute paths
+    """Like the standard "Include" directive, but interprets absolute paths
     "correctly", i.e. relative to source directory.
     """
 
@@ -407,12 +387,12 @@ class Include(BaseInclude, SphinxDirective):
             # We must preserve them and leave them out of the include-read event:
             text = '\n'.join(include_lines[:-2])
 
-            path = Path(relpath(abspath(source), start=self.env.srcdir))
+            path = Path(relpath(Path(source).resolve(), start=self.env.srcdir))
             docname = self.env.docname
 
             # Emit the "include-read" event
             arg = [text]
-            self.env.app.events.emit('include-read', path, docname, arg)
+            self.env.events.emit('include-read', path, docname, arg)
             text = arg[0]
 
             # Split back into lines and reattach the two marker lines
@@ -424,7 +404,7 @@ class Include(BaseInclude, SphinxDirective):
             return StateMachine.insert_input(self.state_machine, include_lines, source)
 
         # Only enable this patch if there are listeners for 'include-read'.
-        if self.env.app.events.listeners.get('include-read'):
+        if self.env.events.listeners.get('include-read'):
             # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
             self.state_machine.insert_input = _insert_input
 
@@ -432,7 +412,7 @@ class Include(BaseInclude, SphinxDirective):
             # docutils "standard" includes, do not do path processing
             return super().run()
         rel_filename, filename = self.env.relfn2path(self.arguments[0])
-        self.arguments[0] = filename
+        self.arguments[0] = str(filename)
         self.env.note_included(filename)
         return super().run()
 
@@ -442,7 +422,6 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     directives.register_directive('sectionauthor', Author)
     directives.register_directive('moduleauthor', Author)
     directives.register_directive('codeauthor', Author)
-    directives.register_directive('seealso', SeeAlso)
     directives.register_directive('tabularcolumns', TabularColumns)
     directives.register_directive('centered', Centered)
     directives.register_directive('acks', Acks)