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

sphinx/environment/adapters/indexentries.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 import unicodedata
 from itertools import groupby
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING
 
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
@@ -13,9 +13,42 @@ from sphinx.util import logging
 from sphinx.util.index_entries import _split_into
 
 if TYPE_CHECKING:
+    from typing import Literal, Optional, Union
+
+    from typing_extensions import TypeAlias
+
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
 
+    _IndexEntryTarget: TypeAlias = tuple[Optional[str], Union[str, Literal[False]]]
+    _IndexEntryTargets: TypeAlias = list[_IndexEntryTarget]
+    _IndexEntryCategoryKey: TypeAlias = Optional[str]
+    _IndexEntrySubItems: TypeAlias = dict[
+        str,
+        tuple[_IndexEntryTargets, _IndexEntryCategoryKey],
+    ]
+    _IndexEntry: TypeAlias = tuple[
+        _IndexEntryTargets,
+        _IndexEntrySubItems,
+        _IndexEntryCategoryKey,
+    ]
+    _IndexEntryMap = dict[str, _IndexEntry]
+    _Index: TypeAlias = list[
+        tuple[
+            str,
+            list[
+                tuple[
+                    str,
+                    tuple[
+                        _IndexEntryTargets,
+                        list[tuple[str, _IndexEntryTargets]],
+                        _IndexEntryCategoryKey
+                    ]
+                ]
+            ]
+        ]
+    ]
+
 logger = logging.getLogger(__name__)
 
 
@@ -24,11 +57,14 @@ class IndexEntries:
         self.env = env
         self.builder: Builder
 
-    def create_index(self, builder: Builder, group_entries: bool = True,
-                     _fixre: re.Pattern = re.compile(r'(.*) ([(][^()]*[)])'),
-                     ) -> list[tuple[str, list[tuple[str, Any]]]]:
+    def create_index(
+        self,
+        builder: Builder,
+        group_entries: bool = True,
+        _fixre: re.Pattern[str] = re.compile(r'(.*) ([(][^()]*[)])'),
+    ) -> _Index:
         """Create the real index from the collected index entries."""
-        new: dict[str, list] = {}
+        new: _IndexEntryMap = {}
 
         rel_uri: str | Literal[False]
         index_domain = self.env.domains['index']
@@ -80,10 +116,10 @@ class IndexEntries:
 
         for (targets, sub_items, _category_key) in new.values():
             targets.sort(key=_key_func_0)
-            for (sub_targets, _0, _sub_category_key) in sub_items.values():
+            for (sub_targets, _sub_category_key) in sub_items.values():
                 sub_targets.sort(key=_key_func_0)
 
-        new_list = sorted(new.items(), key=_key_func_1)
+        new_list: list[tuple[str, _IndexEntry]] = sorted(new.items(), key=_key_func_1)
 
         if group_entries:
             # fixup entries: transform
@@ -94,7 +130,7 @@ class IndexEntries:
             #     (in module foo)
             #     (in module bar)
             old_key = ''
-            old_sub_items: dict[str, list] = {}
+            old_sub_items: _IndexEntrySubItems = {}
             i = 0
             while i < len(new_list):
                 key, (targets, sub_items, category_key) = new_list[i]
@@ -106,7 +142,7 @@ class IndexEntries:
                             # prefixes match: add entry as subitem of the
                             # previous entry
                             old_sub_items.setdefault(
-                                m.group(2), [[], {}, category_key])[0].extend(targets)
+                                m.group(2), ([], category_key))[0].extend(targets)
                             del new_list[i]
                             continue
                         old_key = m.group(1)
@@ -115,26 +151,41 @@ class IndexEntries:
                 old_sub_items = sub_items
                 i += 1
 
-        return [(key_, list(group))
-                for (key_, group) in groupby(new_list, _key_func_3)]
+        grouped = []
+        for (group_key, group) in groupby(new_list, _group_by_func):
+            group_list = []
+            for group_entry in group:
+                entry_key, (targets, sub_items, category_key) = group_entry
+                pairs = [
+                    (sub_key, sub_targets)
+                    for (sub_key, (sub_targets, _sub_category_key))
+                    in sub_items.items()
+                ]
+                pairs.sort(key=_key_func_2)
+                group_list.append((entry_key, (targets, pairs, category_key)))
+            grouped.append((group_key, group_list))
+        return grouped
 
 
 def _add_entry(word: str, subword: str, main: str | None, *,
-               dic: dict[str, list], link: str | Literal[False], key: str | None) -> None:
-    entry = dic.setdefault(word, [[], {}, key])
+               dic: _IndexEntryMap,
+               link: str | Literal[False], key: _IndexEntryCategoryKey) -> None:
+    entry = dic.setdefault(word, ([], {}, key))
     if subword:
-        entry = entry[1].setdefault(subword, [[], {}, key])
+        targets = entry[1].setdefault(subword, ([], key))[0]
+    else:
+        targets = entry[0]
     if link:
-        entry[0].append((main, link))
+        targets.append((main, link))
 
 
-def _key_func_0(entry: tuple[str, str]) -> tuple[bool, str]:
+def _key_func_0(entry: _IndexEntryTarget) -> tuple[bool, str | Literal[False]]:
     """Sort the index entries for same keyword."""
     main, uri = entry
     return not main, uri  # show main entries at first
 
 
-def _key_func_1(entry: tuple[str, list]) -> tuple[tuple[int, str], str]:
+def _key_func_1(entry: tuple[str, _IndexEntry]) -> tuple[tuple[int, str], str]:
     """Sort the index entries"""
     key, (_targets, _sub_items, category_key) = entry
     if category_key:
@@ -155,7 +206,7 @@ def _key_func_1(entry: tuple[str, list]) -> tuple[tuple[int, str], str]:
     return (group, lc_key), entry[0]
 
 
-def _key_func_2(entry: tuple[str, list]) -> str:
+def _key_func_2(entry: tuple[str, _IndexEntryTargets]) -> str:
     """Sort the sub-index entries"""
     key = unicodedata.normalize('NFD', entry[0].lower())
     if key.startswith('\N{RIGHT-TO-LEFT MARK}'):
@@ -165,13 +216,9 @@ def _key_func_2(entry: tuple[str, list]) -> str:
     return key
 
 
-def _key_func_3(entry: tuple[str, list]) -> str:
-    """Group the entries by letter"""
+def _group_by_func(entry: tuple[str, _IndexEntry]) -> str:
+    """Group the entries by letter or category key."""
     key, (targets, sub_items, category_key) = entry
-    # hack: mutating the sub_items dicts to a list in the key_func
-    entry[1][1] = sorted(((sub_key, sub_targets)
-                          for (sub_key, (sub_targets, _0, _sub_category_key))
-                          in sub_items.items()), key=_key_func_2)
 
     if category_key is not None:
         return category_key

sphinx/environment/adapters/toctree.py

@@ -316,7 +316,7 @@ def _toctree_entry(
             # empty toc means: no titles will show up in the toctree
             logger.warning(__('toctree contains reference to document %r that '
                               "doesn't have a title: no link will be generated"),
-                           ref, location=toctreenode)
+                           ref, location=toctreenode, type='toc', subtype='no_title')
     except KeyError:
         # this is raised if the included file does not exist
         ref_path = env.doc2path(ref, False)

sphinx/environment/collectors/__init__.py

@@ -15,9 +15,13 @@ class EnvironmentCollector:
     """An EnvironmentCollector is a specific data collector from each document.
 
     It gathers data and stores :py:class:`BuildEnvironment
-    <sphinx.environment.BuildEnvironment>` as a database.  Examples of specific
-    data would be images, download files, section titles, metadatas, index
+    <sphinx.environment.BuildEnvironment>` as a database.
+    Examples of specific data would be images, download files, section titles, metadatas, index
     entries and toctrees, etc.
+
+    .. note::
+
+        This class essentially wraps a sub-set of :ref:`Sphinx event callbacks <events>`.
     """
 
     listener_ids: dict[str, int] | None = None
@@ -42,6 +46,8 @@ class EnvironmentCollector:
         """Remove specified data of a document.
 
         This method is called on the removal of the document.
+
+        .. seealso:: :event:`env-purge-doc`
         """
         raise NotImplementedError
 
@@ -49,6 +55,8 @@ class EnvironmentCollector:
                     docnames: set[str], other: BuildEnvironment) -> None:
         """Merge in specified data regarding docnames from a different `BuildEnvironment`
         object which coming from a subprocess in parallel builds.
+
+        .. seealso:: :event:`env-merge-info`
         """
         raise NotImplementedError
 
@@ -56,13 +64,17 @@ class EnvironmentCollector:
         """Process a document and gather specific data from it.
 
         This method is called after the document is read.
+
+        .. seealso:: :event:`doctree-read`
         """
         raise NotImplementedError
 
     def get_updated_docs(self, app: Sphinx, env: BuildEnvironment) -> list[str]:
         """Return a list of docnames to re-read.
 
-        This methods is called after reading the whole of documents (experimental).
+        This method is called after reading the whole of documents.
+
+        .. seealso:: :event:`env-get-updated`
         """
         return []
 
@@ -70,6 +82,8 @@ class EnvironmentCollector:
                           added: set[str], changed: set[str], removed: set[str]) -> list[str]:
         """Return a list of docnames to re-read.
 
-        This methods is called before reading the documents.
+        This method is called before reading the documents.
+
+        .. seealso:: :event:`env-get-outdated`
         """
         return []

sphinx/environment/collectors/asset.py

@@ -86,7 +86,7 @@ class ImageCollector(EnvironmentCollector):
             for imgpath in candidates.values():
                 app.env.dependencies[docname].add(imgpath)
                 if not os.access(path.join(app.srcdir, imgpath), os.R_OK):
-                    logger.warning(__('image file not readable: %s') % imgpath,
+                    logger.warning(__('image file not readable: %s'), imgpath,
                                    location=node, type='image', subtype='not_readable')
                     continue
                 app.env.images.add_file(docname, imgpath)
@@ -105,10 +105,10 @@ class ImageCollector(EnvironmentCollector):
                 if mimetype not in candidates:
                     globbed.setdefault(mimetype, []).append(new_imgpath)
             except OSError as err:
-                logger.warning(__('image file %s not readable: %s') % (filename, err),
+                logger.warning(__('image file %s not readable: %s'), filename, err,
                                location=node, type='image', subtype='not_readable')
         for key, files in globbed.items():
-            candidates[key] = sorted(files, key=len)[0]  # select by similarity
+            candidates[key] = min(files, key=len)  # select by similarity
 
 
 class DownloadFileCollector(EnvironmentCollector):
@@ -131,7 +131,7 @@ class DownloadFileCollector(EnvironmentCollector):
                 rel_filename, filename = app.env.relfn2path(targetname, app.env.docname)
                 app.env.dependencies[app.env.docname].add(rel_filename)
                 if not os.access(filename, os.R_OK):
-                    logger.warning(__('download file not readable: %s') % filename,
+                    logger.warning(__('download file not readable: %s'), filename,
                                    location=node, type='download', subtype='not_readable')
                     continue
                 node['filename'] = app.env.dlfiles.add_file(app.env.docname, rel_filename)

sphinx/environment/collectors/toctree.py

@@ -68,8 +68,6 @@ class TocTreeCollector(EnvironmentCollector):
         ) -> nodes.bullet_list | None:
             # list of table of contents entries
             entries: list[Element] = []
-            # cache of parents -> list item
-            memo_parents: dict[tuple[str, ...], nodes.list_item] = {}
             for sectionnode in node:
                 # find all toctree nodes in this section and add them
                 # to the toc (just copying the toctree node which is then
@@ -103,6 +101,8 @@ class TocTreeCollector(EnvironmentCollector):
                         entries.append(onlynode)
                 # check within the section for other node types
                 elif isinstance(sectionnode, nodes.Element):
+                    # cache of parent node -> list item
+                    memo_parents: dict[nodes.Element, nodes.list_item] = {}
                     toctreenode: nodes.Node
                     for toctreenode in sectionnode.findall():
                         if isinstance(toctreenode, nodes.section):
@@ -114,6 +114,10 @@ class TocTreeCollector(EnvironmentCollector):
                             note_toctree(app.env, docname, toctreenode)
                         # add object signatures within a section to the ToC
                         elif isinstance(toctreenode, addnodes.desc):
+                            # The desc has one or more nested desc_signature,
+                            # and then a desc_content, which again may have desc nodes.
+                            # Thus, desc is the one we can bubble up to through parents.
+                            entry: nodes.list_item | None = None
                             for sig_node in toctreenode:
                                 if not isinstance(sig_node, addnodes.desc_signature):
                                     continue
@@ -136,22 +140,28 @@ class TocTreeCollector(EnvironmentCollector):
                                 para = addnodes.compact_paragraph('', '', reference,
                                                                   skip_section_number=True)
                                 entry = nodes.list_item('', para)
-                                *parents, _ = sig_node['_toc_parts']
-                                parents = tuple(parents)
 
-                                # Cache parents tuple
-                                memo_parents[sig_node['_toc_parts']] = entry
-
-                                # Nest children within parents
-                                if parents and parents in memo_parents:
-                                    root_entry = memo_parents[parents]
+                                # Find parent node
+                                parent = sig_node.parent
+                                while parent not in memo_parents and parent != sectionnode:
+                                    parent = parent.parent
+                                # Note, it may both be the limit and in memo_parents,
+                                # prefer memo_parents, so we get the nesting.
+                                if parent in memo_parents:
+                                    root_entry = memo_parents[parent]
                                     if isinstance(root_entry[-1], nodes.bullet_list):
                                         root_entry[-1].append(entry)
                                     else:
                                         root_entry.append(nodes.bullet_list('', entry))
-                                    continue
+                                else:
+                                    assert parent == sectionnode
+                                    entries.append(entry)
 
-                                entries.append(entry)
+                            # Save the latest desc_signature as the one we put sub entries in.
+                            # If there are multiple signatures, then the latest is used.
+                            if entry is not None:
+                                # are there any desc nodes without desc_signature nodes?
+                                memo_parents[toctreenode] = entry
 
             if entries:
                 return nodes.bullet_list('', *entries)
@@ -177,7 +187,10 @@ class TocTreeCollector(EnvironmentCollector):
         env.toc_secnumbers = {}
 
         def _walk_toc(
-            node: Element, secnums: dict, depth: int, titlenode: nodes.title | None = None,
+            node: Element,
+            secnums: dict[str, tuple[int, ...]],
+            depth: int,
+            titlenode: nodes.title | None = None,
         ) -> None:
             # titlenode is the title of the document, it will get assigned a
             # secnumber too, so that it shows up in next/prev/parent rellinks
@@ -206,7 +219,7 @@ class TocTreeCollector(EnvironmentCollector):
                         secnums[reference['anchorname']] = tuple(numstack)
                     else:
                         number = None
-                        secnums[reference['anchorname']] = None
+                        secnums[reference['anchorname']] = ()
                     reference['secnumber'] = number
                     if titlenode:
                         titlenode['secnumber'] = number

sphinx/events.py

@@ -30,21 +30,22 @@ class EventListener(NamedTuple):
 
 # List of all known core events. Maps name to arguments description.
 core_events = {
-    'builder-inited': '',
     'config-inited': 'config',
+    'builder-inited': '',
     'env-get-outdated': 'env, added, changed, removed',
-    'env-get-updated': 'env',
-    'env-purge-doc': 'env, docname',
     'env-before-read-docs': 'env, docnames',
-    'env-check-consistency': 'env',
+    'env-purge-doc': 'env, docname',
     'source-read': 'docname, source text',
     'include-read': 'relative path, parent docname, source text',
     'doctree-read': 'the doctree before being pickled',
     'env-merge-info': 'env, read docnames, other env instance',
+    'env-updated': 'env',
+    'env-get-updated': 'env',
+    'env-check-consistency': 'env',
+    'write-started': 'builder',
+    'doctree-resolved': 'doctree, docname',
     'missing-reference': 'env, node, contnode',
     'warn-missing-reference': 'domain, node',
-    'doctree-resolved': 'doctree, docname',
-    'env-updated': 'env',
     'build-finished': 'exception',
 }