Sphinx 7.1.2__py3-none-any.whl → 7.2.0__py3-none-any.whl

sphinx/search/de.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/en.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/es.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/fi.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/fr.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/hu.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/it.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/ja.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 import os
 import re
 import sys
-from typing import Any, Dict, List
+from typing import TYPE_CHECKING, Any, Dict, List
 
 try:
     import MeCab

sphinx/search/nl.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/no.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/pt.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/ro.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Set
+from typing import TYPE_CHECKING, Dict, Set
 
 import snowballstemmer
 

sphinx/search/ru.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/sv.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
 import snowballstemmer
 

sphinx/search/tr.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Set
+from typing import TYPE_CHECKING, Dict, Set
 
 import snowballstemmer
 

sphinx/search/zh.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import os
 import re
-from typing import Dict, List
+from typing import TYPE_CHECKING, Dict, List
 
 import snowballstemmer
 

sphinx/testing/fixtures.py

@@ -2,17 +2,21 @@
 
 from __future__ import annotations
 
+import shutil
 import subprocess
 import sys
 from collections import namedtuple
 from io import StringIO
-from typing import Any, Callable, Generator
+from typing import TYPE_CHECKING, Any, Callable
 
 import pytest
 
-from sphinx.testing import util
 from sphinx.testing.util import SphinxTestApp, SphinxTestAppWrapperForSkipBuilding
 
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from pathlib import Path
+
 DEFAULT_ENABLED_MARKERS = [
     (
         'sphinx(builder, testroot=None, freshenv=False, confoverrides=None, tags=None,'
@@ -57,7 +61,7 @@ class SharedResult:
 
 @pytest.fixture()
 def app_params(request: Any, test_params: dict, shared_result: SharedResult,
-               sphinx_test_tempdir: str, rootdir: str) -> tuple[dict, dict]:
+               sphinx_test_tempdir: str, rootdir: str) -> _app_params:
     """
     Parameters that are specified by 'pytest.mark.sphinx' for
     sphinx.application.Sphinx initialization
@@ -79,8 +83,8 @@ def app_params(request: Any, test_params: dict, shared_result: SharedResult,
     # ##### process pytest.mark.test_params
     if test_params['shared_result']:
         if 'srcdir' in kwargs:
-            raise pytest.Exception('You can not specify shared_result and '
-                                   'srcdir in same time.')
+            msg = 'You can not specify shared_result and srcdir in same time.'
+            raise pytest.Exception(msg)
         kwargs['srcdir'] = test_params['shared_result']
         restore = shared_result.restore(test_params['shared_result'])
         kwargs.update(restore)
@@ -93,9 +97,12 @@ def app_params(request: Any, test_params: dict, shared_result: SharedResult,
     # special support for sphinx/tests
     if rootdir and not srcdir.exists():
         testroot_path = rootdir / ('test-' + testroot)
-        testroot_path.copytree(srcdir)
+        shutil.copytree(testroot_path, srcdir)
+
+    return _app_params(args, kwargs)
 
-    return namedtuple('app_params', 'args,kwargs')(args, kwargs)  # type: ignore
+
+_app_params = namedtuple('_app_params', 'args,kwargs')
 
 
 @pytest.fixture()
@@ -116,13 +123,13 @@ def test_params(request: Any) -> dict:
     }
     result.update(kwargs)
 
-    if (result['shared_result'] and not isinstance(result['shared_result'], str)):
-        raise pytest.Exception('You can only provide a string type of value '
-                               'for "shared_result" ')
+    if result['shared_result'] and not isinstance(result['shared_result'], str):
+        msg = 'You can only provide a string type of value for "shared_result"'
+        raise pytest.Exception(msg)
     return result
 
 
-@pytest.fixture(scope='function')
+@pytest.fixture()
 def app(test_params: dict, app_params: tuple[dict, dict], make_app: Callable,
         shared_result: SharedResult) -> Generator[SphinxTestApp, None, None]:
     """
@@ -143,7 +150,7 @@ def app(test_params: dict, app_params: tuple[dict, dict], make_app: Callable,
         shared_result.store(test_params['shared_result'], app_)
 
 
-@pytest.fixture(scope='function')
+@pytest.fixture()
 def status(app: SphinxTestApp) -> StringIO:
     """
     Back-compatibility for testing with previous @with_app decorator
@@ -151,7 +158,7 @@ def status(app: SphinxTestApp) -> StringIO:
     return app._status
 
 
-@pytest.fixture(scope='function')
+@pytest.fixture()
 def warning(app: SphinxTestApp) -> StringIO:
     """
     Back-compatibility for testing with previous @with_app decorator
@@ -166,8 +173,6 @@ def make_app(test_params: dict, monkeypatch: Any) -> Generator[Callable, None, N
     if you want to initialize 'app' in your test function. please use this
     instead of using SphinxTestApp class directory.
     """
-    monkeypatch.setattr('sphinx.application.abspath', lambda x: x)
-
     apps = []
     syspath = sys.path[:]
 
@@ -215,21 +220,9 @@ def if_graphviz_found(app: SphinxTestApp) -> None:  # NoQA: PT004
 
 
 @pytest.fixture(scope='session')
-def sphinx_test_tempdir(tmpdir_factory: Any) -> util.path:
-    """
-    Temporary directory wrapped with `path` class.
-    """
-    tmpdir = tmpdir_factory.getbasetemp()
-    return util.path(tmpdir).abspath()
-
-
-@pytest.fixture()
-def tempdir(tmpdir: str) -> util.path:
-    """
-    Temporary directory wrapped with `path` class.
-    This fixture is for back-compatibility with old test implementation.
-    """
-    return util.path(tmpdir)
+def sphinx_test_tempdir(tmp_path_factory: Any) -> Path:
+    """Temporary directory."""
+    return tmp_path_factory.getbasetemp()
 
 
 @pytest.fixture()

sphinx/testing/path.py

@@ -3,11 +3,18 @@ from __future__ import annotations
 import os
 import shutil
 import sys
+import warnings
 from typing import IO, TYPE_CHECKING, Any, Callable
 
+from sphinx.deprecation import RemovedInSphinx90Warning
+
 if TYPE_CHECKING:
     import builtins
 
+warnings.warn("'sphinx.testing.path' is deprecated. "
+              "Use 'os.path' or 'pathlib' instead.",
+              RemovedInSphinx90Warning, stacklevel=2)
+
 FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding()
 
 
@@ -27,6 +34,8 @@ class path(str):
     Represents a path which behaves like a string.
     """
 
+    __slots__ = ()
+
     @property
     def parent(self) -> path:
         """

sphinx/testing/restructuredtext.py

@@ -18,10 +18,18 @@ def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
         parser = RSTParser()
         parser.set_application(app)
         with sphinx_domains(app.env):
-            return publish_doctree(text, path.join(app.srcdir, docname + '.rst'),
-                                   reader=reader,
-                                   parser=parser,
-                                   settings_overrides={'env': app.env,
-                                                       'gettext_compact': True})
+            return publish_doctree(
+                text,
+                path.join(app.srcdir, docname + '.rst'),
+                reader=reader,
+                parser=parser,
+                settings_overrides={
+                    'env': app.env,
+                    'gettext_compact': True,
+                    'input_encoding': 'utf-8',
+                    'output_encoding': 'unicode',
+                    'traceback': True,
+                },
+            )
     finally:
         app.env.temp_data.pop('docname', None)

sphinx/testing/util.py

@@ -1,44 +1,27 @@
 """Sphinx test suite utilities"""
 from __future__ import annotations
 
-import functools
+import contextlib
 import os
 import re
 import sys
 import warnings
-from typing import IO, TYPE_CHECKING, Any, Generator
+from typing import IO, TYPE_CHECKING, Any
 from xml.etree import ElementTree
 
 from docutils import nodes
-from docutils.nodes import Node
 from docutils.parsers.rst import directives, roles
 
 from sphinx import application, locale
 from sphinx.pycode import ModuleAnalyzer
-from sphinx.testing.path import path
-from sphinx.util.osutil import relpath
 
 if TYPE_CHECKING:
     from io import StringIO
+    from pathlib import Path
 
-__all__ = [
-    'Struct', 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding',
-]
+    from docutils.nodes import Node
 
-
-def assert_re_search(regex: re.Pattern, text: str, flags: int = 0) -> None:
-    if not re.search(regex, text, flags):
-        raise AssertionError(f'{regex!r} did not match {text!r}')
-
-
-def assert_not_re_search(regex: re.Pattern, text: str, flags: int = 0) -> None:
-    if re.search(regex, text, flags):
-        raise AssertionError(f'{regex!r} did match {text!r}')
-
-
-def assert_startswith(thing: str, prefix: str) -> None:
-    if not thing.startswith(prefix):
-        raise AssertionError(f'{thing!r} does not start with {prefix!r}')
+__all__ = 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding'
 
 
 def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) -> None:
@@ -73,8 +56,10 @@ def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) ->
             'The node%s does not have any attributes' % xpath
 
         for key, value in kwargs.items():
-            assert key in node, \
-                f'The node{xpath} does not have {key!r} attribute: {node!r}'
+            if key not in node:
+                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}'
 
@@ -85,11 +70,6 @@ def etree_parse(path: str) -> Any:
         return ElementTree.parse(path)  # NoQA: S314  # using known data in tests
 
 
-class Struct:
-    def __init__(self, **kwargs: Any) -> None:
-        self.__dict__.update(kwargs)
-
-
 class SphinxTestApp(application.Sphinx):
     """
     A subclass of :class:`Sphinx` that runs on the test root, with some
@@ -101,8 +81,8 @@ class SphinxTestApp(application.Sphinx):
     def __init__(
         self,
         buildername: str = 'html',
-        srcdir: path | None = None,
-        builddir: path | None = None,
+        srcdir: Path | None = None,
+        builddir: Path | None = None,
         freshenv: bool = False,
         confoverrides: dict | None = None,
         status: IO | None = None,
@@ -115,23 +95,23 @@ class SphinxTestApp(application.Sphinx):
 
         self.docutils_conf_path = srcdir / 'docutils.conf'
         if docutilsconf is not None:
-            self.docutils_conf_path.write_text(docutilsconf)
+            self.docutils_conf_path.write_text(docutilsconf, encoding='utf8')
 
         if builddir is None:
             builddir = srcdir / '_build'
 
         confdir = srcdir
         outdir = builddir.joinpath(buildername)
-        outdir.makedirs(exist_ok=True)
+        outdir.mkdir(parents=True, exist_ok=True)
         doctreedir = builddir.joinpath('doctrees')
-        doctreedir.makedirs(exist_ok=True)
+        doctreedir.mkdir(parents=True, exist_ok=True)
         if confoverrides is None:
             confoverrides = {}
         warningiserror = False
 
         self._saved_path = sys.path[:]
-        self._saved_directives = directives._directives.copy()  # type: ignore
-        self._saved_roles = roles._roles.copy()  # type: ignore
+        self._saved_directives = directives._directives.copy()  # type: ignore[attr-defined]
+        self._saved_roles = roles._roles.copy()  # type: ignore[attr-defined]
 
         self._saved_nodeclasses = {v for v in dir(nodes.GenericNodeVisitor)
                                    if v.startswith('visit_')}
@@ -149,17 +129,15 @@ class SphinxTestApp(application.Sphinx):
         locale.translators.clear()
         sys.path[:] = self._saved_path
         sys.modules.pop('autodoc_fodder', None)
-        directives._directives = self._saved_directives  # type: ignore
-        roles._roles = self._saved_roles  # type: ignore
+        directives._directives = self._saved_directives  # type: ignore[attr-defined]
+        roles._roles = self._saved_roles  # type: ignore[attr-defined]
         for method in dir(nodes.GenericNodeVisitor):
             if method.startswith('visit_') and \
                method not in self._saved_nodeclasses:
                 delattr(nodes.GenericNodeVisitor, 'visit_' + method[6:])
                 delattr(nodes.GenericNodeVisitor, 'depart_' + method[6:])
-        try:
+        with contextlib.suppress(FileNotFoundError):
             os.remove(self.docutils_conf_path)
-        except FileNotFoundError:
-            pass
 
     def __repr__(self) -> str:
         return f'<{self.__class__.__name__} buildername={self.builder.name!r}>'
@@ -183,32 +161,11 @@ class SphinxTestAppWrapperForSkipBuilding:
         return getattr(self.app, name)
 
     def build(self, *args: Any, **kwargs: Any) -> None:
-        if not self.app.outdir.listdir():  # type: ignore
+        if not os.listdir(self.app.outdir):
             # if listdir is empty, do build.
             self.app.build(*args, **kwargs)
             # otherwise, we can use built cache
 
 
-_unicode_literals_re = re.compile(r'u(".*?")|u(\'.*?\')')
-
-
-def find_files(root: str, suffix: str | None = None) -> Generator[str, None, None]:
-    for dirpath, _dirs, files in os.walk(root, followlinks=True):
-        dirpath = path(dirpath)
-        for f in [f for f in files if not suffix or f.endswith(suffix)]:
-            fpath = dirpath / f
-            yield relpath(fpath, root)
-
-
 def strip_escseq(text: str) -> str:
     return re.sub('\x1b.*?m', '', text)
-
-
-def simple_decorator(f):
-    """
-    A simple decorator that does nothing, for tests to use.
-    """
-    @functools.wraps(f)
-    def wrapper(*args, **kwargs):
-        return f(*args, **kwargs)
-    return wrapper

sphinx/texinputs/sphinxlatexobjects.sty

@@ -310,22 +310,22 @@
 \newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
 \newenvironment{optionlist}[1]
 {\begin{list}{}
-  {\setlength{\labelwidth}{#1}
-   \setlength{\rightmargin}{1cm}
-   \setlength{\leftmargin}{\rightmargin}
-   \addtolength{\leftmargin}{\labelwidth}
-   \addtolength{\leftmargin}{\labelsep}
-   \renewcommand{\makelabel}{\optionlistlabel}}
+  {\setlength{\labelwidth}{#1}%
+   \setlength{\rightmargin}{1cm}%
+   \setlength{\leftmargin}{\rightmargin}%
+   \addtolength{\leftmargin}{\labelwidth}%
+   \addtolength{\leftmargin}{\labelsep}%
+   \renewcommand{\makelabel}{\optionlistlabel}}%
 }{\end{list}}
 
 \newlength{\lineblockindentation}
 \setlength{\lineblockindentation}{2.5em}
 \newenvironment{lineblock}[1]
 {\begin{list}{}
-  {\setlength{\partopsep}{\parskip}
-   \addtolength{\partopsep}{\baselineskip}
+  {\setlength{\partopsep}{\parskip}%
+   \addtolength{\partopsep}{\baselineskip}%
    \topsep0pt\itemsep0.15\baselineskip\parsep0pt
-   \leftmargin#1\relax}
+   \leftmargin#1\relax}%
  \raggedright}
 {\end{list}}
 
@@ -351,12 +351,12 @@
 \DUprovidelength{\DUlineblockindent}{2.5em}
 \ifdefined\DUlineblock\else
   \newenvironment{DUlineblock}[1]{%
-    \list{}{\setlength{\partopsep}{\parskip}
-            \addtolength{\partopsep}{\baselineskip}
-            \setlength{\topsep}{0pt}
-            \setlength{\itemsep}{0.15\baselineskip}
-            \setlength{\parsep}{0pt}
-            \setlength{\leftmargin}{#1}}
+    \list{}{\setlength{\partopsep}{\parskip}%
+            \addtolength{\partopsep}{\baselineskip}%
+            \setlength{\topsep}{0pt}%
+            \setlength{\itemsep}{0.15\baselineskip}%
+            \setlength{\parsep}{0pt}%
+            \setlength{\leftmargin}{#1}}%
     \raggedright
   }
   {\endlist}

sphinx/themes/agogo/static/agogo.css_t

@@ -19,6 +19,10 @@ body {
   line-height: 1.4em;
   color: black;
   background-color: {{ theme_bgcolor }};
+
+  /* fix for background colors breaking at horizontal
+    scrolling on smaller devices */
+  min-width: fit-content;
 }
 
 
@@ -41,6 +45,10 @@ a {
   color: {{ theme_linkcolor }};
 }
 
+a:visited {
+  color: #551a8b;
+}
+
 div.bodywrapper a, div.footer a {
   text-decoration: underline;
 }
@@ -127,8 +135,7 @@ dt:target, .highlighted {
 /* Header */
 
 div.header {
-  padding-top: 10px;
-  padding-bottom: 10px;
+  padding: 1em;
 }
 
 div.header .headertitle {
@@ -165,8 +172,7 @@ img.logo {
 /* Content */
 div.content-wrapper {
   background-color: white;
-  padding-top: 20px;
-  padding-bottom: 20px;
+  padding: 1em;
 }
 
 div.document {

sphinx/themes/basic/layout.html

@@ -102,7 +102,7 @@
 {%- if html_tag %}
 {{ html_tag }}
 {%- else %}
-<html{% if language is not none %} lang="{{ language }}"{% endif %}>
+<html{% if language is not none %} lang="{{ language }}"{% endif %} data-content_root="{{ content_root }}">
 {%- endif %}
   <head>
     <meta charset="{{ encoding }}" />

sphinx/themes/basic/static/basic.css_t

@@ -237,6 +237,10 @@ a.headerlink {
     visibility: hidden;
 }
 
+a:visited {
+    color: #551A8B;
+}
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,

sphinx/themes/basic/static/documentation_options.js_t

@@ -1,5 +1,4 @@
-var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
+const DOCUMENTATION_OPTIONS = {
     VERSION: '{{ release|e }}',
     LANGUAGE: '{{ language }}',
     COLLAPSE_INDEX: false,