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

sphinx/testing/path.py

@@ -4,16 +4,17 @@ import os
 import shutil
 import sys
 import warnings
-from typing import IO, TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from sphinx.deprecation import RemovedInSphinx90Warning
 
 if TYPE_CHECKING:
     import builtins
     from collections.abc import Callable
+    from typing import IO, Any
 
 warnings.warn(
-    "'sphinx.testing.path' is deprecated. " "Use 'os.path' or 'pathlib' instead.",
+    "'sphinx.testing.path' is deprecated. Use 'os.path' or 'pathlib' instead.",
     RemovedInSphinx90Warning,
     stacklevel=2,
 )
@@ -32,57 +33,41 @@ def getumask() -> int:
 UMASK = getumask()
 
 
-class path(str):
-    """
-    Represents a path which behaves like a string.
-    """
+class path(str):  # NoQA: FURB189
+    """Represents a path which behaves like a string."""
 
     __slots__ = ()
 
     @property
     def parent(self) -> path:
-        """
-        The name of the directory the file or directory is in.
-        """
+        """The name of the directory the file or directory is in."""
         return self.__class__(os.path.dirname(self))
 
     def basename(self) -> str:
         return os.path.basename(self)
 
     def abspath(self) -> path:
-        """
-        Returns the absolute path.
-        """
+        """Returns the absolute path."""
         return self.__class__(os.path.abspath(self))
 
     def isabs(self) -> bool:
-        """
-        Returns ``True`` if the path is absolute.
-        """
+        """Returns ``True`` if the path is absolute."""
         return os.path.isabs(self)
 
     def isdir(self) -> bool:
-        """
-        Returns ``True`` if the path is a directory.
-        """
+        """Returns ``True`` if the path is a directory."""
         return os.path.isdir(self)
 
     def isfile(self) -> bool:
-        """
-        Returns ``True`` if the path is a file.
-        """
+        """Returns ``True`` if the path is a file."""
         return os.path.isfile(self)
 
     def islink(self) -> bool:
-        """
-        Returns ``True`` if the path is a symbolic link.
-        """
+        """Returns ``True`` if the path is a symbolic link."""
         return os.path.islink(self)
 
     def ismount(self) -> bool:
-        """
-        Returns ``True`` if the path is a mount point.
-        """
+        """Returns ``True`` if the path is a mount point."""
         return os.path.ismount(self)
 
     def rmtree(
@@ -90,8 +75,7 @@ class path(str):
         ignore_errors: bool = False,
         onerror: Callable[[Callable[..., Any], str, Any], object] | None = None,
     ) -> None:
-        """
-        Removes the file or directory and any files or directories it may
+        """Removes the file or directory and any files or directories it may
         contain.
 
         :param ignore_errors:
@@ -108,8 +92,7 @@ class path(str):
         shutil.rmtree(self, ignore_errors=ignore_errors, onerror=onerror)
 
     def copytree(self, destination: str, symlinks: bool = False) -> None:
-        """
-        Recursively copy a directory to the given `destination`. If the given
+        """Recursively copy a directory to the given `destination`. If the given
         `destination` does not exist it will be created.
 
         :param symlinks:
@@ -130,8 +113,7 @@ class path(str):
                     os.chmod(os.path.join(root, name), 0o644 & ~UMASK)
 
     def movetree(self, destination: str) -> None:
-        """
-        Recursively move the file or directory to the given `destination`
+        """Recursively move the file or directory to the given `destination`
         similar to the  Unix "mv" command.
 
         If the `destination` is a file it may be overwritten depending on the
@@ -142,47 +124,36 @@ class path(str):
     move = movetree
 
     def unlink(self) -> None:
-        """
-        Removes a file.
-        """
+        """Removes a file."""
         os.unlink(self)
 
     def stat(self) -> Any:
-        """
-        Returns a stat of the file.
-        """
+        """Returns a stat of the file."""
         return os.stat(self)
 
     def utime(self, arg: Any) -> None:
         os.utime(self, arg)
 
     def open(self, mode: str = 'r', **kwargs: Any) -> IO[str]:
-        return open(self, mode, **kwargs)  # NoQA: SIM115
+        return open(self, mode, **kwargs)
 
     def write_text(self, text: str, encoding: str = 'utf-8', **kwargs: Any) -> None:
-        """
-        Writes the given `text` to the file.
-        """
+        """Writes the given `text` to the file."""
         with open(self, 'w', encoding=encoding, **kwargs) as f:
             f.write(text)
 
     def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
-        """
-        Returns the text in the file.
-        """
+        """Returns the text in the file."""
         with open(self, encoding=encoding, **kwargs) as f:
             return f.read()
 
     def read_bytes(self) -> builtins.bytes:
-        """
-        Returns the bytes in the file.
-        """
+        """Returns the bytes in the file."""
         with open(self, mode='rb') as f:
             return f.read()
 
     def write_bytes(self, bytes: bytes, append: bool = False) -> None:
-        """
-        Writes the given `bytes` to the file.
+        """Writes the given `bytes` to the file.
 
         :param append:
             If ``True`` given `bytes` are added at the end of the file.
@@ -195,28 +166,21 @@ class path(str):
             f.write(bytes)
 
     def exists(self) -> bool:
-        """
-        Returns ``True`` if the path exist.
-        """
+        """Returns ``True`` if the path exist."""
         return os.path.exists(self)
 
     def lexists(self) -> bool:
-        """
-        Returns ``True`` if the path exists unless it is a broken symbolic
+        """Returns ``True`` if the path exists unless it is a broken symbolic
         link.
         """
         return os.path.lexists(self)
 
     def makedirs(self, mode: int = 0o777, exist_ok: bool = False) -> None:
-        """
-        Recursively create directories.
-        """
+        """Recursively create directories."""
         os.makedirs(self, mode, exist_ok=exist_ok)
 
     def joinpath(self, *args: Any) -> path:
-        """
-        Joins the path with the argument given and returns the result.
-        """
+        """Joins the path with the argument given and returns the result."""
         return self.__class__(os.path.join(self, *map(self.__class__, args)))
 
     def listdir(self) -> list[str]:

sphinx/testing/restructuredtext.py

@@ -1,30 +1,36 @@
-from os import path
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 
-from docutils import nodes
 from docutils.core import publish_doctree
 
-from sphinx.application import Sphinx
 from sphinx.io import SphinxStandaloneReader
 from sphinx.parsers import RSTParser
 from sphinx.util.docutils import sphinx_domains
 
+if TYPE_CHECKING:
+    from docutils import nodes
+
+    from sphinx.application import Sphinx
+
 
 def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
     """Parse a string as reStructuredText with Sphinx application."""
+    env = app.env
     try:
-        app.env.temp_data['docname'] = docname
+        app.env.current_document.docname = docname
         reader = SphinxStandaloneReader()
         reader.setup(app)
         parser = RSTParser()
         parser.set_application(app)
-        with sphinx_domains(app.env):
+        with sphinx_domains(env):
             return publish_doctree(
                 text,
-                path.join(app.srcdir, docname + '.rst'),
+                str(app.srcdir / f'{docname}.rst'),
                 reader=reader,
                 parser=parser,
                 settings_overrides={
-                    'env': app.env,
+                    'env': env,
                     'gettext_compact': True,
                     'input_encoding': 'utf-8',
                     'output_encoding': 'unicode',
@@ -32,4 +38,4 @@ def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
                 },
             )
     finally:
-        app.env.temp_data.pop('docname', None)
+        env.current_document.docname = ''

sphinx/testing/util.py

@@ -4,8 +4,6 @@ from __future__ import annotations
 
 __all__ = ('SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding')
 
-import contextlib
-import os
 import sys
 from io import StringIO
 from types import MappingProxyType
@@ -17,10 +15,11 @@ from docutils.parsers.rst import directives, roles
 import sphinx.application
 import sphinx.locale
 import sphinx.pycode
-from sphinx.util.console import strip_colors
+from sphinx._cli.util.errors import strip_escape_sequences
 from sphinx.util.docutils import additional_nodes
 
 if TYPE_CHECKING:
+    import os
     from collections.abc import Mapping, Sequence
     from pathlib import Path
     from typing import Any
@@ -40,9 +39,9 @@ def assert_node(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any) ->
                     assert (
                         isinstance(node, nodes.Element)
                     ), f'The node{xpath} does not have any children'  # fmt: skip
-                    assert (
-                        len(node) == 1
-                    ), f'The node{xpath} has {len(node)} child nodes, not one'
+                    assert len(node) == 1, (
+                        f'The node{xpath} has {len(node)} child nodes, not one'
+                    )
                     assert_node(node[0], cls[1:], xpath=xpath + '[0]', **kwargs)
         elif isinstance(cls, tuple):
             assert (
@@ -71,9 +70,9 @@ def assert_node(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any) ->
                 if (key := key.replace('_', '-')) not in node:
                     msg = f'The node{xpath} does not have {key!r} attribute: {node!r}'
                     raise AssertionError(msg)
-            assert (
-                node[key] == value
-            ), f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
+            assert node[key] == value, (
+                f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
+            )
 
 
 # keep this to restrict the API usage and to have a correct return type
@@ -224,15 +223,16 @@ class SphinxTestApp(sphinx.application.Sphinx):
     def cleanup(self, doctrees: bool = False) -> None:
         sys.path[:] = self._saved_path
         _clean_up_global_state()
-        with contextlib.suppress(FileNotFoundError):
-            os.remove(self.docutils_conf_path)
+        try:
+            self.docutils_conf_path.unlink(missing_ok=True)
+        except OSError as exc:
+            if exc.errno != 30:  # Ignore "read-only file system" errors
+                raise
 
     def __repr__(self) -> str:
         return f'<{self.__class__.__name__} buildername={self._builder_name!r}>'
 
-    def build(
-        self, force_all: bool = False, filenames: list[str] | None = None
-    ) -> None:
+    def build(self, force_all: bool = False, filenames: Sequence[Path] = ()) -> None:
         self.env._pickled_doctree_cache.clear()
         super().build(force_all, filenames)
 
@@ -244,10 +244,8 @@ class SphinxTestAppWrapperForSkipBuilding(SphinxTestApp):
     if it has already been built and there are any output files.
     """
 
-    def build(
-        self, force_all: bool = False, filenames: list[str] | None = None
-    ) -> None:
-        if not os.listdir(self.outdir):
+    def build(self, force_all: bool = False, filenames: Sequence[Path] = ()) -> None:
+        if not list(self.outdir.iterdir()):
             # if listdir is empty, do build.
             super().build(force_all, filenames)
             # otherwise, we can use built cache
@@ -273,7 +271,11 @@ def _clean_up_global_state() -> None:
 
 # deprecated name -> (object to return, canonical path or '', removal version)
 _DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
-    'strip_escseq': (strip_colors, 'sphinx.util.console.strip_colors', (9, 0)),
+    'strip_escseq': (
+        strip_escape_sequences,
+        'sphinx.util.console.strip_escape_sequences',
+        (9, 0),
+    ),
 }
 
 

sphinx/texinputs/make.bat.jinja

@@ -1,50 +1,50 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-pushd %~dp0
-
-{% if latex_engine in ('platex', 'uplatex') -%}
-REM latexmkrc is read then overridden by latexmkjarc
-set PDFLATEX=latexmk -r latexmkjarc -pdfdvi -dvi- -ps-
-{% else -%}
-set PDFLATEX=latexmk -pdf -dvi- -ps-
-{% endif %}
-set "LATEXOPTS= "
-
-{% if xindy_use -%}
-set XINDYOPTS={{ xindy_lang_option }} -M sphinx.xdy
-{% if latex_engine == 'pdflatex' -%}
-set XINDYOPTS=%XINDYOPTS% -M LICRlatin2utf8.xdy
-{% if xindy_cyrillic -%}
-set XINDYOPTS=%XINDYOPTS% -M LICRcyr2utf8.xdy
-{% endif -%}
-{% endif -%}
-{% if xindy_cyrillic -%}
-set XINDYOPTS=%XINDYOPTS% -M LatinRules.xdy
-{% endif -%}
-set XINDYOPTS=%XINDYOPTS% -I xelatex
-{% endif -%}
-
-
-if "%1" == "" goto all-pdf
-
-if "%1" == "all-pdf" (
-	:all-pdf
-	for %%i in (*.tex) do (
-		%PDFLATEX% %LATEXMKOPTS% %%i
-	)
-	goto end
-)
-
-if "%1" == "all-pdf-ja" (
-	goto all-pdf
-)
-
-if "%1" == "clean" (
-	del /q /s *.dvi *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz *.fls *.fdb_latexmk
-	goto end
-)
-
-:end
-popd
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+pushd %~dp0
+
+{% if latex_engine in ('platex', 'uplatex') -%}
+REM latexmkrc is read then overridden by latexmkjarc
+set PDFLATEX=latexmk -r latexmkjarc -pdfdvi -dvi- -ps-
+{% else -%}
+set PDFLATEX=latexmk -pdf -dvi- -ps-
+{% endif %}
+set "LATEXOPTS= "
+
+{% if xindy_use -%}
+set XINDYOPTS={{ xindy_lang_option }} -M sphinx.xdy
+{% if latex_engine == 'pdflatex' -%}
+set XINDYOPTS=%XINDYOPTS% -M LICRlatin2utf8.xdy
+{% if xindy_cyrillic -%}
+set XINDYOPTS=%XINDYOPTS% -M LICRcyr2utf8.xdy
+{% endif -%}
+{% endif -%}
+{% if xindy_cyrillic -%}
+set XINDYOPTS=%XINDYOPTS% -M LatinRules.xdy
+{% endif -%}
+set XINDYOPTS=%XINDYOPTS% -I xelatex
+{% endif -%}
+
+
+if "%1" == "" goto all-pdf
+
+if "%1" == "all-pdf" (
+	:all-pdf
+	for %%i in (*.tex) do (
+		%PDFLATEX% %LATEXMKOPTS% %%i
+	)
+	goto end
+)
+
+if "%1" == "all-pdf-ja" (
+	goto all-pdf
+)
+
+if "%1" == "clean" (
+	del /q /s *.dvi *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz *.fls *.fdb_latexmk
+	goto end
+)
+
+:end
+popd

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2024/10/11 v8.1.1 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2024/11/23 v8.2.0 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -1098,12 +1098,13 @@
 % Some of these defaults got already set.  But we now list them all explicitly
 % for a complete initial configuration of reset storage.
 % At 7.4.0, \fboxrule and \fboxsep replaced by 0.4pt and 3pt which are anyhow
-% the defaults for these LaTeX dimensions.
+% the defaults for these LaTeX dimensions. 8.2.0 corrected border-radius
+% default back to 3pt (\fboxsep) not 0.4pt (\fboxrule).
 \let\spx@boxes@sphinxbox@defaults\@gobble
 \sphinxboxsetup{%
                 border-width=0.4pt,
                 padding=3pt,
-                border-radius=0.4pt,
+                border-radius=3pt,
                 box-shadow=none,
 % MEMO: as xcolor is loaded, \spx@defineorletcolor has a "\colorlet" branch
 % which makes this syntax acceptable and avoids duplicating here the values.

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -32,7 +32,7 @@
 %   sphinxlatexshadowbox.sty, and handles both "with icon" and "without
 %   icon" situations).
 %
-% The sphinxlightbox environment is kept for backward compatiblity, for user
+% The sphinxlightbox environment is kept for backward compatibility, for user
 % custom code which used it via custom definitions done in preamble or via
 % raw latex directive.
 % MEMO: here is for example how sphinxnote was formerly defined:

sphinx/texinputs/sphinxlatexobjects.sty

@@ -1,7 +1,7 @@
 %% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexobjects}[2023/07/23 documentation environments]
+\ProvidesPackage{sphinxlatexobjects}[2025/02/11 documentation environments]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -279,18 +279,37 @@
 \newcommand{\pysigstopmultiline}{\sphinxsigismultilinefalse\itemsep\sphinxsignaturesep}%
 
 % Production lists
+% This simply outputs the lines as is, in monospace font.  Refers #13326.
+% (the left padding for multi-line alignment is from the nodes themselves,
+%  and latex is configured below to obey such horizontal whitespace).
+%
+% - The legacy code used longtable and hardcoded the separator as ::=
+%   via dedicated macros defined by the environment itself.
+% - Here the separator is part of the node.  Any extra LaTeX mark-up would
+%   have to originate from the writer itself to decorate it.
+% - The legacy code used strangely \parindent and \indent.  Possibly
+%   (unchecked) due to an earlier tabular usage, but a longtable does not
+%   work in paragraph mode, so \parindent was without effect and
+%   \indent only caused some extra blank line above display.
+% - The table had some whitespace on its left, which we imitate here via
+%   \parindent usage (which works in our context...).
 %
 \newenvironment{productionlist}{%
-%  \def\sphinxoptional##1{{\Large[}##1{\Large]}}
-  \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
-  \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
-  \parindent=2em
-  \indent
-  \setlength{\LTpre}{0pt}%
-  \setlength{\LTpost}{0pt}%
-  \begin{longtable}[l]{lcl}
+  \bigskip      % imitate close enough legacy vertical whitespace, which was
+                % visibly excessive
+  \ttfamily     % needed for space tokens to have same width as letters
+  \parindent1em % width of a "quad", font-dependent, usually circa width of 2
+                % letters
+  \obeylines    % line in = line out
+  \parskip\z@skip % prevent the parskip vertical whitespace between lines,
+                  % which are technically to LaTeX now each its own paragraph
+  \@vobeyspaces % obey whitespace
+  % now a technicality to, only locally to this environment, prevent the
+  % suppression of indentation of first line, if it comes right after
+  % \section. Cf package indentfirst from which the code is borrowed.
+  \let\@afterindentfalse\@afterindenttrue\@afterindenttrue
 }{%
-  \end{longtable}
+  \par % does not hurt...
 }
 
 % Definition lists; requested by AMK for HOWTO documents.  Probably useful

sphinx/themes/basic/static/searchtools.js

@@ -513,9 +513,11 @@ const Search = {
     // perform the search on the required terms
     searchTerms.forEach((word) => {
       const files = [];
+      // find documents, if any, containing the query word in their text/title term indices
+      // use Object.hasOwnProperty to avoid mismatching against prototype properties
       const arr = [
-        { files: terms[word], score: Scorer.term },
-        { files: titleTerms[word], score: Scorer.title },
+        { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term },
+        { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title },
       ];
       // add support for partial matches
       if (word.length > 2) {
@@ -547,8 +549,9 @@ const Search = {
 
         // set score for the word in each file
         recordFiles.forEach((file) => {
-          if (!scoreMap.has(file)) scoreMap.set(file, {});
-          scoreMap.get(file)[word] = record.score;
+          if (!scoreMap.has(file)) scoreMap.set(file, new Map());
+          const fileScores = scoreMap.get(file);
+          fileScores.set(word, record.score);
         });
       });
 
@@ -587,7 +590,7 @@ const Search = {
         break;
 
       // select one (max) score for the file.
-      const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
+      const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w)));
       // add result to the result list
       results.push([
         docNames[file],