Sphinx 7.3.7__py3-none-any.whl → 7.4.1__py3-none-any.whl

sphinx/roles.py

@@ -374,7 +374,7 @@ class Manpage(ReferenceRole):
         inner: nodes.Node
         text = self.title[1:] if self.disabled else self.title
         if not self.disabled and self.config.manpages_url:
-            uri = self.config.manpages_url.format(**info)
+            uri = self.config.manpages_url.format_map(info)
             inner = nodes.reference('', text, classes=[self.name], refuri=uri)
         else:
             inner = nodes.Text(text)

sphinx/search/__init__.py

@@ -52,11 +52,11 @@ class SearchLanguage:
        This class is used to preprocess search word which Sphinx HTML readers
        type, before searching index. Default implementation does nothing.
     """
-    lang: str | None = None
-    language_name: str | None = None
+    lang: str = ''
+    language_name: str = ''
     stopwords: set[str] = set()
     js_splitter_code: str = ""
-    js_stemmer_rawcode: str | None = None
+    js_stemmer_rawcode: str = ''
     js_stemmer_code = """
 /**
  * Dummy stemmer for languages without stemming rules.
@@ -198,7 +198,7 @@ def _is_meta_keywords(
 @dataclasses.dataclass
 class WordStore:
     words: list[str] = dataclasses.field(default_factory=list)
-    titles: list[tuple[str, str]] = dataclasses.field(default_factory=list)
+    titles: list[tuple[str, str | None]] = dataclasses.field(default_factory=list)
     title_words: list[str] = dataclasses.field(default_factory=list)
 
 
@@ -253,7 +253,7 @@ class IndexBuilder:
     def __init__(self, env: BuildEnvironment, lang: str, options: dict[str, str], scoring: str) -> None:
         self.env = env
         # docname -> title
-        self._titles: dict[str, str] = env._search_index_titles
+        self._titles: dict[str, str | None] = env._search_index_titles
         # docname -> filename
         self._filenames: dict[str, str] = env._search_index_filenames
         # stemmed words -> set(docname)
@@ -261,7 +261,7 @@ class IndexBuilder:
         # stemmed words in titles -> set(docname)
         self._title_mapping: dict[str, set[str]] = env._search_index_title_mapping
         # docname -> all titles in document
-        self._all_titles: dict[str, list[tuple[str, str]]] = env._search_index_all_titles
+        self._all_titles: dict[str, list[tuple[str, str | None]]] = env._search_index_all_titles
         # docname -> list(index entry)
         self._index_entries: dict[str, list[tuple[str, str, str]]] = env._search_index_index_entries
         # objtype -> index
@@ -369,6 +369,13 @@ class IndexBuilder:
         return rv
 
     def get_terms(self, fn2index: dict[str, int]) -> tuple[dict[str, list[int] | int], dict[str, list[int] | int]]:
+        """
+        Return a mapping of document and title terms to their corresponding sorted document IDs.
+
+        When a term is only found within a single document, then the value for that term will be
+        an integer value.  When a term is found within multiple documents, the value will be a list
+        of integers.
+        """
         rvs: tuple[dict[str, list[int] | int], dict[str, list[int] | int]] = ({}, {})
         for rv, mapping in zip(rvs, (self._mapping, self._title_mapping)):
             for k, v in mapping.items():
@@ -391,7 +398,7 @@ class IndexBuilder:
         objtypes = {v: k[0] + ':' + k[1] for (k, v) in self._objtypes.items()}
         objnames = self._objnames
 
-        alltitles: dict[str, list[tuple[int, str]]] = {}
+        alltitles: dict[str, list[tuple[int, str | None]]] = {}
         for docname, titlelist in sorted(self._all_titles.items()):
             for title, titleid in titlelist:
                 alltitles.setdefault(title, []).append((fn2index[docname], titleid))
@@ -502,9 +509,10 @@ class IndexBuilder:
             elif isinstance(node, nodes.Text):
                 word_store.words.extend(split(node.astext()))
             elif isinstance(node, nodes.title):
-                title = node.astext()
+                title, is_main_title = node.astext(), len(word_store.titles) == 0
                 ids = node.parent['ids']
-                word_store.titles.append((title, ids[0] if ids else None))
+                title_node_id = None if is_main_title else ids[0] if ids else None
+                word_store.titles.append((title, title_node_id))
                 word_store.title_words.extend(split(title))
             for child in node.children:
                 _visit_nodes(child)

sphinx/templates/quickstart/{root_doc.rst_t → root_doc.rst.jinja}

@@ -3,19 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to {{ project }}'s documentation!
-==========={{ project_underline }}=================
+{{ project }} documentation
+{{ project_underline }}==============
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
 
 .. toctree::
    :maxdepth: {{ mastertocmaxdepth }}
    :caption: Contents:
 
 {{ mastertoctree }}
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

sphinx/testing/fixtures.py

@@ -68,10 +68,10 @@ class SharedResult:
         }
 
 
-@pytest.fixture()
+@pytest.fixture
 def app_params(
     request: Any,
-    test_params: dict,
+    test_params: dict[str, Any],
     shared_result: SharedResult,
     sphinx_test_tempdir: str,
     rootdir: str,
@@ -117,8 +117,8 @@ def app_params(
 _app_params = namedtuple('_app_params', 'args,kwargs')
 
 
-@pytest.fixture()
-def test_params(request: Any) -> dict:
+@pytest.fixture
+def test_params(request: Any) -> dict[str, Any]:
     """
     Test parameters that are specified by 'pytest.mark.test_params'
 
@@ -141,11 +141,11 @@ def test_params(request: Any) -> dict:
     return result
 
 
-@pytest.fixture()
+@pytest.fixture
 def app(
-    test_params: dict,
-    app_params: tuple[dict, dict],
-    make_app: Callable,
+    test_params: dict[str, Any],
+    app_params: _app_params,
+    make_app: Callable[[], SphinxTestApp],
     shared_result: SharedResult,
 ) -> Iterator[SphinxTestApp]:
     """
@@ -159,14 +159,14 @@ def app(
     print('# builder:', app_.builder.name)
     print('# srcdir:', app_.srcdir)
     print('# outdir:', app_.outdir)
-    print('# status:', '\n' + app_._status.getvalue())
-    print('# warning:', '\n' + app_._warning.getvalue())
+    print('# status:', '\n' + app_.status.getvalue())
+    print('# warning:', '\n' + app_.warning.getvalue())
 
     if test_params['shared_result']:
         shared_result.store(test_params['shared_result'], app_)
 
 
-@pytest.fixture()
+@pytest.fixture
 def status(app: SphinxTestApp) -> StringIO:
     """
     Back-compatibility for testing with previous @with_app decorator
@@ -174,7 +174,7 @@ def status(app: SphinxTestApp) -> StringIO:
     return app.status
 
 
-@pytest.fixture()
+@pytest.fixture
 def warning(app: SphinxTestApp) -> StringIO:
     """
     Back-compatibility for testing with previous @with_app decorator
@@ -182,8 +182,8 @@ def warning(app: SphinxTestApp) -> StringIO:
     return app.warning
 
 
-@pytest.fixture()
-def make_app(test_params: dict, monkeypatch: Any) -> Iterator[Callable]:
+@pytest.fixture
+def make_app(test_params: dict[str, Any]) -> Iterator[Callable[[], SphinxTestApp]]:
     """
     Provides make_app function to initialize SphinxTestApp instance.
     if you want to initialize 'app' in your test function. please use this
@@ -196,10 +196,12 @@ def make_app(test_params: dict, monkeypatch: Any) -> Iterator[Callable]:
         status, warning = StringIO(), StringIO()
         kwargs.setdefault('status', status)
         kwargs.setdefault('warning', warning)
-        app_: Any = SphinxTestApp(*args, **kwargs)
-        apps.append(app_)
+        app_: SphinxTestApp
         if test_params['shared_result']:
-            app_ = SphinxTestAppWrapperForSkipBuilding(app_)
+            app_ = SphinxTestAppWrapperForSkipBuilding(*args, **kwargs)
+        else:
+            app_ = SphinxTestApp(*args, **kwargs)
+        apps.append(app_)
         return app_
     yield make
 
@@ -208,7 +210,7 @@ def make_app(test_params: dict, monkeypatch: Any) -> Iterator[Callable]:
         app_.cleanup()
 
 
-@pytest.fixture()
+@pytest.fixture
 def shared_result() -> SharedResult:
     return SharedResult()
 
@@ -218,7 +220,7 @@ def _shared_result_cache() -> None:
     SharedResult.cache.clear()
 
 
-@pytest.fixture()
+@pytest.fixture
 def if_graphviz_found(app: SphinxTestApp) -> None:  # NoQA: PT004
     """
     The test will be skipped when using 'if_graphviz_found' fixture and graphviz
@@ -242,7 +244,7 @@ def sphinx_test_tempdir(tmp_path_factory: Any) -> Path:
     return tmp_path_factory.getbasetemp()
 
 
-@pytest.fixture()
+@pytest.fixture
 def rollback_sysmodules() -> Iterator[None]:  # NoQA: PT004
     """
     Rollback sys.modules to its value before testing to unload modules

sphinx/testing/path.py

@@ -82,7 +82,11 @@ class path(str):
         """
         return os.path.ismount(self)
 
-    def rmtree(self, ignore_errors: bool = False, onerror: Callable | None = None) -> None:
+    def rmtree(
+        self,
+        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
         contain.
@@ -149,7 +153,7 @@ class path(str):
     def utime(self, arg: Any) -> None:
         os.utime(self, arg)
 
-    def open(self, mode: str = 'r', **kwargs: Any) -> IO:
+    def open(self, mode: str = 'r', **kwargs: Any) -> IO[str]:
         return open(self, mode, **kwargs)  # NoQA: SIM115
 
     def write_text(self, text: str, encoding: str = 'utf-8', **kwargs: Any) -> None:

sphinx/testing/util.py

@@ -11,7 +11,6 @@ from io import StringIO
 from types import MappingProxyType
 from typing import TYPE_CHECKING
 
-from defusedxml.ElementTree import parse as xml_parse
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
 
@@ -22,7 +21,7 @@ from sphinx.util.console import strip_colors
 from sphinx.util.docutils import additional_nodes
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from collections.abc import Mapping, Sequence
     from pathlib import Path
     from typing import Any
     from xml.etree.ElementTree import ElementTree
@@ -73,6 +72,8 @@ def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) ->
 # keep this to restrict the API usage and to have a correct return type
 def etree_parse(path: str | os.PathLike[str]) -> ElementTree:
     """Parse a file into a (safe) XML element tree."""
+    from defusedxml.ElementTree import parse as xml_parse
+
     return xml_parse(path)
 
 
@@ -111,7 +112,7 @@ class SphinxTestApp(sphinx.application.Sphinx):
         confoverrides: dict[str, Any] | None = None,
         status: StringIO | None = None,
         warning: StringIO | None = None,
-        tags: list[str] | None = None,
+        tags: Sequence[str] = (),
         docutils_conf: str | None = None,  # extra constructor argument
         parallel: int = 0,
         # additional arguments at the end to keep the signature
@@ -204,23 +205,17 @@ class SphinxTestApp(sphinx.application.Sphinx):
         super().build(force_all, filenames)
 
 
-class SphinxTestAppWrapperForSkipBuilding:
+class SphinxTestAppWrapperForSkipBuilding(SphinxTestApp):
     """A wrapper for SphinxTestApp.
 
     This class is used to speed up the test by skipping ``app.build()``
     if it has already been built and there are any output files.
     """
 
-    def __init__(self, app_: SphinxTestApp) -> None:
-        self.app = app_
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self.app, name)
-
-    def build(self, *args: Any, **kwargs: Any) -> None:
-        if not os.listdir(self.app.outdir):
+    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+        if not os.listdir(self.outdir):
             # if listdir is empty, do build.
-            self.app.build(*args, **kwargs)
+            super().build(force_all, filenames)
             # otherwise, we can use built cache