Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/environment/adapters/indexentries.py

@@ -40,10 +40,10 @@ if TYPE_CHECKING:
                     tuple[
                         _IndexEntryTargets,
                         list[tuple[str, _IndexEntryTargets]],
-                        _IndexEntryCategoryKey
-                    ]
+                        _IndexEntryCategoryKey,
+                    ],
                 ]
-            ]
+            ],
         ]
     ]
 
@@ -65,7 +65,7 @@ class IndexEntries:
         new: _IndexEntryMap = {}
 
         rel_uri: str | Literal[False]
-        index_domain = self.env.domains['index']
+        index_domain = self.env.domains.index_domain
         for docname, entries in index_domain.entries.items():
             try:
                 rel_uri = builder.get_relative_uri('genindex', docname)
@@ -80,41 +80,77 @@ class IndexEntries:
                         try:
                             entry, sub_entry = _split_into(2, 'single', value)
                         except ValueError:
-                            entry, = _split_into(1, 'single', value)
+                            (entry,) = _split_into(1, 'single', value)
                             sub_entry = ''
-                        _add_entry(entry, sub_entry, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            entry, sub_entry, main, dic=new, link=uri, key=category_key
+                        )
                     elif entry_type == 'pair':
                         first, second = _split_into(2, 'pair', value)
-                        _add_entry(first, second, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(second, first, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            first, second, main, dic=new, link=uri, key=category_key
+                        )
+                        _add_entry(
+                            second, first, main, dic=new, link=uri, key=category_key
+                        )
                     elif entry_type == 'triple':
                         first, second, third = _split_into(3, 'triple', value)
-                        _add_entry(first, second + ' ' + third, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(second, third + ', ' + first, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(third, first + ' ' + second, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            first,
+                            second + ' ' + third,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
+                        _add_entry(
+                            second,
+                            third + ', ' + first,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
+                        _add_entry(
+                            third,
+                            first + ' ' + second,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
                     elif entry_type == 'see':
                         first, second = _split_into(2, 'see', value)
-                        _add_entry(first, _('see %s') % second, None,
-                                   dic=new, link=False, key=category_key)
+                        _add_entry(
+                            first,
+                            _('see %s') % second,
+                            None,
+                            dic=new,
+                            link=False,
+                            key=category_key,
+                        )
                     elif entry_type == 'seealso':
                         first, second = _split_into(2, 'see', value)
-                        _add_entry(first, _('see also %s') % second, None,
-                                   dic=new, link=False, key=category_key)
+                        _add_entry(
+                            first,
+                            _('see also %s') % second,
+                            None,
+                            dic=new,
+                            link=False,
+                            key=category_key,
+                        )
                     else:
-                        logger.warning(__('unknown index entry type %r'), entry_type,
-                                       location=docname)
+                        logger.warning(
+                            __('unknown index entry type %r'),
+                            entry_type,
+                            location=docname,
+                        )
                 except ValueError as err:
                     logger.warning(str(err), location=docname)
 
-        for (targets, sub_items, _category_key) in new.values():
+        for targets, sub_items, _category_key in new.values():
             targets.sort(key=_key_func_0)
-            for (sub_targets, _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: list[tuple[str, _IndexEntry]] = sorted(new.items(), key=_key_func_1)
@@ -139,8 +175,8 @@ class IndexEntries:
                         if old_key == m.group(1):
                             # prefixes match: add entry as subitem of the
                             # previous entry
-                            old_sub_items.setdefault(
-                                m.group(2), ([], category_key))[0].extend(targets)
+                            prev = old_sub_items.setdefault(m[2], ([], category_key))
+                            prev[0].extend(targets)
                             del new_list[i]
                             continue
                         old_key = m.group(1)
@@ -150,14 +186,13 @@ class IndexEntries:
                 i += 1
 
         grouped = []
-        for (group_key, group) in groupby(new_list, _group_by_func):
+        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()
+                    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)))
@@ -165,9 +200,15 @@ class IndexEntries:
         return grouped
 
 
-def _add_entry(word: str, subword: str, main: str | None, *,
-               dic: _IndexEntryMap,
-               link: str | Literal[False], key: _IndexEntryCategoryKey) -> None:
+def _add_entry(
+    word: str,
+    subword: str,
+    main: str | None,
+    *,
+    dic: _IndexEntryMap,
+    link: str | Literal[False],
+    key: _IndexEntryCategoryKey,
+) -> None:
     entry = dic.setdefault(word, ([], {}, key))
     if subword:
         targets = entry[1].setdefault(subword, ([], key))[0]

sphinx/environment/adapters/toctree.py

@@ -24,7 +24,9 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def note_toctree(env: BuildEnvironment, docname: str, toctreenode: addnodes.toctree) -> None:
+def note_toctree(
+    env: BuildEnvironment, docname: str, toctreenode: addnodes.toctree
+) -> None:
     """Note a TOC tree directive in a document and gather information about
     file relations from it.
     """
@@ -87,9 +89,7 @@ def global_toctree_for_doc(
         )
         for toctree_node in env.master_doctree.findall(addnodes.toctree)
     )
-    toctrees = [
-        toctree for toctree in resolved if toctree is not None
-    ]
+    toctrees = [toctree for toctree in resolved if toctree is not None]
 
     if not toctrees:
         return None
@@ -100,9 +100,16 @@ def global_toctree_for_doc(
 
 
 def _resolve_toctree(
-    env: BuildEnvironment, docname: str, builder: Builder, toctree: addnodes.toctree, *,
-    prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-    collapse: bool = False, includehidden: bool = False,
+    env: BuildEnvironment,
+    docname: str,
+    builder: Builder,
+    toctree: addnodes.toctree,
+    *,
+    prune: bool = True,
+    maxdepth: int = 0,
+    titles_only: bool = False,
+    collapse: bool = False,
+    includehidden: bool = False,
 ) -> Element | None:
     """Resolve a *toctree* node into individual bullet lists with titles
     as items, returning None (if no containing titles are found) or
@@ -178,9 +185,13 @@ def _resolve_toctree(
 
     # prune the tree to maxdepth, also set toc depth and current classes
     _toctree_add_classes(newnode, 1, docname)
-    newnode = _toctree_copy(newnode, 1, maxdepth if prune else 0, collapse, builder.tags)
+    newnode = _toctree_copy(
+        newnode, 1, maxdepth if prune else 0, collapse, builder.tags
+    )
 
-    if isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0:  # No titles found
+    if (
+        isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0
+    ):  # No titles found
         return None
 
     # set the target paths in the toctrees (they are not known at TOC
@@ -208,11 +219,20 @@ def _entries_from_toctree(
 ) -> list[Element]:
     """Return TOC entries for a toctree node."""
     entries: list[Element] = []
-    for (title, ref) in toctreenode['entries']:
+    for title, ref in toctreenode['entries']:
         try:
             toc, refdoc = _toctree_entry(
-                title, ref, env, prune, collapse, tags, toctree_ancestors,
-                included, excluded, toctreenode, parents,
+                title,
+                ref,
+                env,
+                prune,
+                collapse,
+                tags,
+                toctree_ancestors,
+                included,
+                excluded,
+                toctreenode,
+                parents,
             )
         except LookupError:
             continue
@@ -294,10 +314,14 @@ def _toctree_entry(
             toc = _toctree_generated_entry(title, ref)
         else:
             if ref in parents:
-                logger.warning(__('circular toctree references '
-                                  'detected, ignoring: %s <- %s'),
-                               ref, ' <- '.join(parents),
-                               location=ref, type='toc', subtype='circular')
+                logger.warning(
+                    __('circular toctree references ' 'detected, ignoring: %s <- %s'),
+                    ref,
+                    ' <- '.join(parents),
+                    location=ref,
+                    type='toc',
+                    subtype='circular',
+                )
                 msg = 'circular reference'
                 raise LookupError(msg)
 
@@ -314,9 +338,16 @@ def _toctree_entry(
 
         if not toc.children:
             # 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, type='toc', subtype='no_title')
+            logger.warning(
+                __(
+                    'toctree contains reference to document %r that '
+                    "doesn't have a title: no link will be generated"
+                ),
+                ref,
+                location=toctreenode,
+                type='toc',
+                subtype='no_title',
+            )
     except KeyError:
         # this is raised if the included file does not exist
         ref_path = str(env.doc2path(ref, False))
@@ -335,9 +366,9 @@ def _toctree_entry(
 def _toctree_url_entry(title: str, ref: str) -> nodes.bullet_list:
     if title is None:
         title = ref
-    reference = nodes.reference('', '', internal=False,
-                                refuri=ref, anchorname='',
-                                *[nodes.Text(title)])
+    reference = nodes.reference(
+        '', '', internal=False, refuri=ref, anchorname='', *[nodes.Text(title)]
+    )
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     toc = nodes.bullet_list('', item)
@@ -345,16 +376,17 @@ def _toctree_url_entry(title: str, ref: str) -> nodes.bullet_list:
 
 
 def _toctree_self_entry(
-    title: str, ref: str, titles: dict[str, nodes.title],
+    title: str,
+    ref: str,
+    titles: dict[str, nodes.title],
 ) -> nodes.bullet_list:
     # 'self' refers to the document from which this
     # toctree originates
     if not title:
         title = clean_astext(titles[ref])
-    reference = nodes.reference('', '', internal=True,
-                                refuri=ref,
-                                anchorname='',
-                                *[nodes.Text(title)])
+    reference = nodes.reference(
+        '', '', internal=True, refuri=ref, anchorname='', *[nodes.Text(title)]
+    )
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     # don't show subitems
@@ -368,8 +400,7 @@ def _toctree_generated_entry(title: str, ref: str) -> nodes.bullet_list:
     docname, sectionname = StandardDomain._virtual_doc_names[ref]
     if not title:
         title = sectionname
-    reference = nodes.reference('', title, internal=True,
-                                refuri=docname, anchorname='')
+    reference = nodes.reference('', title, internal=True, refuri=docname, anchorname='')
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     # don't show subitems
@@ -434,11 +465,13 @@ def _toctree_add_classes(node: Element, depth: int, docname: str) -> None:
 ET = TypeVar('ET', bound=Element)
 
 
-def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tags) -> ET:
+def _toctree_copy(
+    node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tags
+) -> ET:
     """Utility: Cut and deep-copy a TOC at a specified depth."""
-    keep_bullet_list_sub_nodes = (depth <= 1
-                                  or ((depth <= maxdepth or maxdepth <= 0)
-                                      and (not collapse or 'iscurrent' in node)))
+    keep_bullet_list_sub_nodes = depth <= 1 or (
+        (depth <= maxdepth or maxdepth <= 0) and (not collapse or 'iscurrent' in node)
+    )
 
     copy = node.copy()
     for subnode in node.children:
@@ -459,9 +492,15 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
             # only keep children if the only node matches the tags
             if _only_node_keep_children(subnode, tags):
                 for child in subnode.children:
-                    copy.append(_toctree_copy(
-                        child, depth, maxdepth, collapse, tags,  # type: ignore[type-var]
-                    ))
+                    copy.append(
+                        _toctree_copy(
+                            child,
+                            depth,
+                            maxdepth,
+                            collapse,
+                            tags,  # type: ignore[type-var]
+                        )
+                    )
         elif isinstance(subnode, nodes.reference | nodes.title):
             # deep copy references and captions
             sub_node_copy = subnode.copy()
@@ -476,7 +515,8 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
 
 
 def _get_toctree_ancestors(
-    toctree_includes: dict[str, list[str]], docname: str,
+    toctree_includes: dict[str, list[str]],
+    docname: str,
 ) -> Set[str]:
     parent: dict[str, str] = {}
     for p, children in toctree_includes.items():
@@ -497,11 +537,22 @@ class TocTree:
     def note(self, docname: str, toctreenode: addnodes.toctree) -> None:
         note_toctree(self.env, docname, toctreenode)
 
-    def resolve(self, docname: str, builder: Builder, toctree: addnodes.toctree,
-                prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-                collapse: bool = False, includehidden: bool = False) -> Element | None:
+    def resolve(
+        self,
+        docname: str,
+        builder: Builder,
+        toctree: addnodes.toctree,
+        prune: bool = True,
+        maxdepth: int = 0,
+        titles_only: bool = False,
+        collapse: bool = False,
+        includehidden: bool = False,
+    ) -> Element | None:
         return _resolve_toctree(
-            self.env, docname, builder, toctree,
+            self.env,
+            docname,
+            builder,
+            toctree,
             prune=prune,
             maxdepth=maxdepth,
             titles_only=titles_only,
@@ -516,6 +567,12 @@ class TocTree:
         return document_toc(self.env, docname, self.env.app.builder.tags)
 
     def get_toctree_for(
-        self, docname: str, builder: Builder, collapse: bool, **kwargs: Any,
+        self,
+        docname: str,
+        builder: Builder,
+        collapse: bool,
+        **kwargs: Any,
     ) -> Element | None:
-        return global_toctree_for_doc(self.env, docname, builder, collapse=collapse, **kwargs)
+        return global_toctree_for_doc(
+            self.env, docname, builder, collapse=collapse, **kwargs
+        )

sphinx/environment/collectors/__init__.py

@@ -29,10 +29,10 @@ class EnvironmentCollector:
     def enable(self, app: Sphinx) -> None:
         assert self.listener_ids is None
         self.listener_ids = {
-            'doctree-read':     app.connect('doctree-read', self.process_doc),
-            'env-merge-info':   app.connect('env-merge-info', self.merge_other),
-            'env-purge-doc':    app.connect('env-purge-doc', self.clear_doc),
-            'env-get-updated':  app.connect('env-get-updated', self.get_updated_docs),
+            'doctree-read': app.connect('doctree-read', self.process_doc),
+            'env-merge-info': app.connect('env-merge-info', self.merge_other),
+            'env-purge-doc': app.connect('env-purge-doc', self.clear_doc),
+            'env-get-updated': app.connect('env-get-updated', self.get_updated_docs),
             'env-get-outdated': app.connect('env-get-outdated', self.get_outdated_docs),
         }
 
@@ -51,8 +51,13 @@ class EnvironmentCollector:
         """
         raise NotImplementedError
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        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.
 
@@ -78,8 +83,14 @@ class EnvironmentCollector:
         """
         return []
 
-    def get_outdated_docs(self, app: Sphinx, env: BuildEnvironment,
-                          added: set[str], changed: set[str], removed: set[str]) -> list[str]:
+    def get_outdated_docs(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        added: set[str],
+        changed: set[str],
+        removed: set[str],
+    ) -> list[str]:
         """Return a list of docnames to re-read.
 
         This method is called before reading the documents.

sphinx/environment/collectors/asset.py

@@ -33,8 +33,13 @@ class ImageCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.images.purge_doc(docname)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         env.images.merge_other(docnames, other.images)
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
@@ -86,17 +91,26 @@ 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,
-                                   location=node, type='image', subtype='not_readable')
+                    logger.warning(
+                        __('image file not readable: %s'),
+                        imgpath,
+                        location=node,
+                        type='image',
+                        subtype='not_readable',
+                    )
                     continue
                 app.env.images.add_file(docname, imgpath)
 
-    def collect_candidates(self, env: BuildEnvironment, imgpath: str,
-                           candidates: dict[str, str], node: Node) -> None:
+    def collect_candidates(
+        self,
+        env: BuildEnvironment,
+        imgpath: str,
+        candidates: dict[str, str],
+        node: Node,
+    ) -> None:
         globbed: dict[str, list[str]] = {}
         for filename in glob(imgpath):
-            new_imgpath = relative_path(path.join(env.srcdir, 'dummy'),
-                                        filename)
+            new_imgpath = relative_path(path.join(env.srcdir, 'dummy'), filename)
             try:
                 mimetype = guess_mimetype(filename)
                 if mimetype is None:
@@ -105,8 +119,14 @@ 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,
-                               location=node, type='image', subtype='not_readable')
+                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] = min(files, key=len)  # select by similarity
 
@@ -117,8 +137,13 @@ class DownloadFileCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.dlfiles.purge_doc(docname)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         env.dlfiles.merge_other(docnames, other.dlfiles)
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
@@ -131,10 +156,17 @@ 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,
-                                   location=node, type='download', subtype='not_readable')
+                    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)
+                node['filename'] = app.env.dlfiles.add_file(
+                    app.env.docname, rel_filename
+                )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/environment/collectors/dependencies.py

@@ -25,8 +25,13 @@ class DependenciesCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.dependencies.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             if docname in other.dependencies:
                 env.dependencies[docname] = other.dependencies[docname]
@@ -43,8 +48,7 @@ class DependenciesCollector(EnvironmentCollector):
             # one relative to the srcdir
             if isinstance(dep, bytes):
                 dep = dep.decode(fs_encoding)
-            relpath = relative_path(frompath,
-                                    path.normpath(path.join(cwd, dep)))
+            relpath = relative_path(frompath, path.normpath(path.join(cwd, dep)))
             app.env.dependencies[app.env.docname].add(relpath)
 
 

sphinx/environment/collectors/metadata.py

@@ -20,8 +20,13 @@ class MetadataCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.metadata.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             env.metadata[docname] = other.metadata[docname]
 

sphinx/environment/collectors/title.py

@@ -22,8 +22,13 @@ class TitleCollector(EnvironmentCollector):
         env.titles.pop(docname, None)
         env.longtitles.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             env.titles[docname] = other.titles[docname]
             env.longtitles[docname] = other.longtitles[docname]