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

sphinx/environment/adapters/indexentries.py

@@ -31,21 +31,18 @@ if TYPE_CHECKING:
         _IndexEntryCategoryKey,
     ]
     _IndexEntryMap: TypeAlias = dict[str, _IndexEntry]
-    _Index: TypeAlias = list[
+
+    # Used by ``create_index()`` for 'the real index'
+    _RealIndexEntry: TypeAlias = tuple[
+        str,
         tuple[
-            str,
-            list[
-                tuple[
-                    str,
-                    tuple[
-                        _IndexEntryTargets,
-                        list[tuple[str, _IndexEntryTargets]],
-                        _IndexEntryCategoryKey,
-                    ],
-                ]
-            ],
-        ]
+            _IndexEntryTargets,
+            list[tuple[str, _IndexEntryTargets]],
+            _IndexEntryCategoryKey,
+        ],
     ]
+    _RealIndexEntries: TypeAlias = list[_RealIndexEntry]
+    _Index: TypeAlias = list[tuple[str, _RealIndexEntries]]
 
 logger = logging.getLogger(__name__)
 
@@ -144,9 +141,10 @@ class IndexEntries:
                             __('unknown index entry type %r'),
                             entry_type,
                             location=docname,
+                            type='index',
                         )
                 except ValueError as err:
-                    logger.warning(str(err), location=docname)
+                    logger.warning(str(err), location=docname, type='index')
 
         for targets, sub_items, _category_key in new.values():
             targets.sort(key=_key_func_0)
@@ -231,8 +229,7 @@ def _key_func_1(entry: tuple[str, _IndexEntry]) -> tuple[tuple[int, str], str]:
         # using the specified category key to sort
         key = category_key
     lc_key = unicodedata.normalize('NFD', key.lower())
-    if lc_key.startswith('\N{RIGHT-TO-LEFT MARK}'):
-        lc_key = lc_key[1:]
+    lc_key = lc_key.removeprefix('\N{RIGHT-TO-LEFT MARK}')
 
     if not lc_key[0:1].isalpha() and not lc_key.startswith('_'):
         # put symbols at the front of the index (0)
@@ -248,8 +245,7 @@ def _key_func_1(entry: tuple[str, _IndexEntry]) -> tuple[tuple[int, str], 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}'):
-        key = key[1:]
+    key = key.removeprefix('\N{RIGHT-TO-LEFT MARK}')
     if key[0:1].isalpha() or key.startswith('_'):
         key = chr(127) + key
     return key
@@ -263,8 +259,7 @@ def _group_by_func(entry: tuple[str, _IndexEntry]) -> str:
         return category_key
 
     # now calculate the key
-    if key.startswith('\N{RIGHT-TO-LEFT MARK}'):
-        key = key[1:]
+    key = key.removeprefix('\N{RIGHT-TO-LEFT MARK}')
     letter = unicodedata.normalize('NFD', key[0])[0].upper()
     if letter.isalpha() or letter == '_':
         return letter

sphinx/environment/adapters/toctree.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, TypeVar
 
 from docutils import nodes
-from docutils.nodes import Element, Node
+from docutils.nodes import Element
 
 from sphinx import addnodes
 from sphinx.locale import __
@@ -15,6 +15,9 @@ from sphinx.util.nodes import _only_node_keep_children, clean_astext
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Set
+    from typing import Any
+
+    from docutils.nodes import Node
 
     from sphinx.builders import Builder
     from sphinx.environment import BuildEnvironment
@@ -86,6 +89,7 @@ def global_toctree_for_doc(
             titles_only=titles_only,
             collapse=collapse,
             includehidden=includehidden,
+            tags=builder.tags,
         )
         for toctree_node in env.master_doctree.findall(addnodes.toctree)
     )
@@ -110,6 +114,7 @@ def _resolve_toctree(
     titles_only: bool = False,
     collapse: bool = False,
     includehidden: bool = False,
+    tags: Tags,
 ) -> Element | None:
     """Resolve a *toctree* node into individual bullet lists with titles
     as items, returning None (if no containing titles are found) or
@@ -141,7 +146,8 @@ def _resolve_toctree(
     # </ul>
     #
     # The transformation is made in two passes in order to avoid
-    # interactions between marking and pruning the tree (see bug #1046).
+    # interactions between marking and pruning the tree.
+    # See: https://github.com/sphinx-doc/sphinx/issues/1046
 
     toctree_ancestors = _get_toctree_ancestors(env.toctree_includes, docname)
     included = Matcher(env.config.include_patterns)
@@ -159,7 +165,7 @@ def _resolve_toctree(
         titles_only,
         collapse,
         includehidden,
-        builder.tags,
+        tags,
         toctree_ancestors,
         included,
         excluded,
@@ -315,7 +321,7 @@ def _toctree_entry(
         else:
             if ref in parents:
                 logger.warning(
-                    __('circular toctree references ' 'detected, ignoring: %s <- %s'),
+                    __('circular toctree references detected, ignoring: %s <- %s'),
                     ref,
                     ' <- '.join(parents),
                     location=ref,
@@ -353,12 +359,15 @@ def _toctree_entry(
         ref_path = str(env.doc2path(ref, False))
         if excluded(ref_path):
             message = __('toctree contains reference to excluded document %r')
+            subtype = 'excluded'
         elif not included(ref_path):
             message = __('toctree contains reference to non-included document %r')
+            subtype = 'not_included'
         else:
-            message = __('toctree contains reference to nonexisting document %r')
+            message = __('toctree contains reference to non-existing document %r')
+            subtype = 'not_readable'
 
-        logger.warning(message, ref, location=toctreenode)
+        logger.warning(message, ref, location=toctreenode, type='toc', subtype=subtype)
         raise
     return toc, refdoc
 
@@ -510,7 +519,7 @@ def _toctree_copy(
             copy.append(sub_node_copy)
         else:
             msg = f'Unexpected node type {subnode.__class__.__name__!r}!'
-            raise ValueError(msg)
+            raise ValueError(msg)  # NoQA: TRY004
     return copy
 
 
@@ -558,13 +567,14 @@ class TocTree:
             titles_only=titles_only,
             collapse=collapse,
             includehidden=includehidden,
+            tags=builder.tags,
         )
 
     def get_toctree_ancestors(self, docname: str) -> list[str]:
         return [*_get_toctree_ancestors(self.env.toctree_includes, docname)]
 
     def get_toc_for(self, docname: str, builder: Builder) -> Node:
-        return document_toc(self.env, docname, self.env.app.builder.tags)
+        return document_toc(self.env, docname, self.env._tags)
 
     def get_toctree_for(
         self,

sphinx/environment/collectors/__init__.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils import nodes
 
     from sphinx.application import Sphinx
@@ -55,7 +57,7 @@ class EnvironmentCollector:
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         """Merge in specified data regarding docnames from a different `BuildEnvironment`

sphinx/environment/collectors/asset.py

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 import os
+import os.path
 from glob import glob
-from os import path
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from docutils import nodes
-from docutils.utils import relative_path
 
 from sphinx import addnodes
 from sphinx.environment.collectors import EnvironmentCollector
@@ -16,8 +16,11 @@ from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.i18n import get_image_filename_for_language, search_image_for_language
 from sphinx.util.images import guess_mimetype
+from sphinx.util.osutil import _relative_path
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
@@ -37,7 +40,7 @@ class ImageCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         env.images.merge_other(docnames, other.images)
@@ -70,9 +73,9 @@ class ImageCollector(EnvironmentCollector):
                 # Search language-specific figures at first
                 i18n_imguri = get_image_filename_for_language(imguri, app.env)
                 _, full_i18n_imgpath = app.env.relfn2path(i18n_imguri, docname)
-                self.collect_candidates(app.env, full_i18n_imgpath, candidates, node)
+                self.collect_candidates(app.srcdir, full_i18n_imgpath, candidates, node)
 
-                self.collect_candidates(app.env, full_imgpath, candidates, node)
+                self.collect_candidates(app.srcdir, full_imgpath, candidates, node)
             else:
                 # substitute imguri by figure_language_filename
                 # (ex. foo.png -> foo.en.png)
@@ -89,8 +92,8 @@ class ImageCollector(EnvironmentCollector):
             # map image paths to unique image names (so that they can be put
             # into a single directory)
             for imgpath in candidates.values():
-                app.env.dependencies[docname].add(imgpath)
-                if not os.access(path.join(app.srcdir, imgpath), os.R_OK):
+                app.env.note_dependency(imgpath)
+                if not os.access(app.srcdir / imgpath, os.R_OK):
                     logger.warning(
                         __('image file not readable: %s'),
                         imgpath,
@@ -103,21 +106,21 @@ class ImageCollector(EnvironmentCollector):
 
     def collect_candidates(
         self,
-        env: BuildEnvironment,
+        srcdir: Path,
         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)
+        for filename in glob(imgpath):  # NoQA: PTH207
+            new_imgpath = _relative_path(Path(filename), srcdir)
             try:
                 mimetype = guess_mimetype(filename)
                 if mimetype is None:
-                    basename, suffix = path.splitext(filename)
+                    basename, suffix = os.path.splitext(filename)
                     mimetype = 'image/x-' + suffix[1:]
                 if mimetype not in candidates:
-                    globbed.setdefault(mimetype, []).append(new_imgpath)
+                    globbed.setdefault(mimetype, []).append(new_imgpath.as_posix())
             except OSError as err:
                 logger.warning(
                     __('image file %s not readable: %s'),
@@ -141,7 +144,7 @@ class DownloadFileCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         env.dlfiles.merge_other(docnames, other.dlfiles)
@@ -154,7 +157,7 @@ class DownloadFileCollector(EnvironmentCollector):
                 node['refuri'] = targetname
             else:
                 rel_filename, filename = app.env.relfn2path(targetname, app.env.docname)
-                app.env.dependencies[app.env.docname].add(rel_filename)
+                app.env.note_dependency(rel_filename)
                 if not os.access(filename, os.R_OK):
                     logger.warning(
                         __('download file not readable: %s'),
@@ -166,7 +169,7 @@ class DownloadFileCollector(EnvironmentCollector):
                     continue
                 node['filename'] = app.env.dlfiles.add_file(
                     app.env.docname, rel_filename
-                )
+                ).as_posix()
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/environment/collectors/dependencies.py

@@ -2,16 +2,15 @@
 
 from __future__ import annotations
 
-import os
-from os import path
+from pathlib import Path
 from typing import TYPE_CHECKING
 
-from docutils.utils import relative_path
-
 from sphinx.environment.collectors import EnvironmentCollector
-from sphinx.util.osutil import fs_encoding
+from sphinx.util.osutil import _relative_path, fs_encoding
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from docutils import nodes
 
     from sphinx.application import Sphinx
@@ -29,7 +28,7 @@ class DependenciesCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         for docname in docnames:
@@ -38,8 +37,7 @@ class DependenciesCollector(EnvironmentCollector):
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         """Process docutils-generated dependency info."""
-        cwd = os.getcwd()
-        frompath = path.join(path.normpath(app.srcdir), 'dummy')
+        cwd = Path.cwd()
         deps = doctree.settings.record_dependencies
         if not deps:
             return
@@ -48,8 +46,8 @@ 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)))
-            app.env.dependencies[app.env.docname].add(relpath)
+            relpath = _relative_path(cwd / dep, app.srcdir)
+            app.env.note_dependency(relpath)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/environment/collectors/metadata.py

@@ -9,6 +9,8 @@ from docutils import nodes
 from sphinx.environment.collectors import EnvironmentCollector
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata
@@ -24,7 +26,7 @@ class MetadataCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         for docname in docnames:
@@ -43,12 +45,12 @@ class MetadataCollector(EnvironmentCollector):
             for node in doctree[index]:  # type: ignore[attr-defined]
                 # nodes are multiply inherited...
                 if isinstance(node, nodes.authors):
-                    authors = cast(list[nodes.author], node)
+                    authors = cast('list[nodes.author]', node)
                     md['authors'] = [author.astext() for author in authors]
                 elif isinstance(node, nodes.field):
                     assert len(node) == 2
-                    field_name = cast(nodes.field_name, node[0])
-                    field_body = cast(nodes.field_body, node[1])
+                    field_name = cast('nodes.field_name', node[0])
+                    field_body = cast('nodes.field_body', node[1])
                     md[field_name.astext()] = field_body.astext()
                 elif isinstance(node, nodes.TextElement):
                     # other children must be TextElement

sphinx/environment/collectors/title.py

@@ -10,6 +10,8 @@ from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.transforms import SphinxContentsFilter
 
 if TYPE_CHECKING:
+    from collections.abc import Set
+
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.util.typing import ExtensionMetadata
@@ -26,7 +28,7 @@ class TitleCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         for docname in docnames:

sphinx/environment/collectors/toctree.py

@@ -15,7 +15,7 @@ from sphinx.transforms import SphinxContentsFilter
 from sphinx.util import logging, url_re
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Sequence, Set
 
     from docutils.nodes import Element, Node
 
@@ -47,7 +47,7 @@ class TocTreeCollector(EnvironmentCollector):
         self,
         app: Sphinx,
         env: BuildEnvironment,
-        docnames: set[str],
+        docnames: Set[str],
         other: BuildEnvironment,
     ) -> None:
         for docname in docnames:
@@ -219,7 +219,7 @@ class TocTreeCollector(EnvironmentCollector):
                     _walk_toc(subnode, secnums, depth - 1, titlenode)
                     numstack.pop()
                     titlenode = None
-                elif isinstance(subnode, nodes.list_item):  # NoQA: SIM114
+                elif isinstance(subnode, nodes.list_item):
                     _walk_toc(subnode, secnums, depth, titlenode)
                     titlenode = None
                 elif isinstance(subnode, addnodes.only):
@@ -232,7 +232,7 @@ class TocTreeCollector(EnvironmentCollector):
                     if 'skip_section_number' in subnode:
                         continue
                     numstack[-1] += 1
-                    reference = cast(nodes.reference, subnode[0])
+                    reference = cast('nodes.reference', subnode[0])
                     if depth > 0:
                         number = numstack.copy()
                         secnums[reference['anchorname']] = tuple(numstack)

sphinx/errors.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import Any
-
 
 class SphinxError(Exception):
     """Base class for Sphinx errors.
@@ -109,7 +107,7 @@ class SphinxParallelError(SphinxError):
 
     category = 'Sphinx parallel build error'
 
-    def __init__(self, message: str, traceback: Any) -> None:
+    def __init__(self, message: str, traceback: str) -> None:
         self.message = message
         self.traceback = traceback
 

sphinx/events.py

@@ -36,7 +36,7 @@ logger = logging.getLogger(__name__)
 
 class EventListener(NamedTuple):
     id: int
-    handler: Callable
+    handler: Callable[..., Any]
     priority: int
 
 
@@ -150,7 +150,7 @@ class EventManager:
         self,
         name: Literal['env-merge-info'],
         callback: Callable[
-            [Sphinx, BuildEnvironment, list[str], BuildEnvironment], None
+            [Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None
         ],
         priority: int,
     ) -> int: ...
@@ -364,7 +364,7 @@ class EventManager:
         priority: int,
     ) -> int: ...
 
-    def connect(self, name: str, callback: Callable, priority: int) -> int:
+    def connect(self, name: str, callback: Callable[..., Any], priority: int) -> int:
         """Connect a handler to specific event."""
         if name not in self.events:
             raise ExtensionError(__('Unknown event name: %s') % name)
@@ -386,7 +386,7 @@ class EventManager:
         name: str,
         *args: Any,
         allowed_exceptions: tuple[type[Exception], ...] = (),
-    ) -> list:
+    ) -> list[Any]:
         """Emit a Sphinx event."""
         # not every object likes to be repr()'d (think
         # random stuff coming via autodoc)

sphinx/ext/apidoc/__init__.py

@@ -0,0 +1,66 @@
+"""Creates reST files corresponding to Python modules for code documentation.
+
+Parses a directory tree looking for Python modules and packages and creates
+ReST files appropriately to create code documentation with Sphinx.  It also
+creates a modules index (named modules.<suffix>).
+
+This is derived from the "sphinx-autopackage" script, which is:
+Copyright 2008 Société des arts technologiques (SAT),
+https://sat.qc.ca/
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import sphinx
+from sphinx.ext.apidoc._cli import main
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+__all__: Sequence[str] = 'main', 'setup'
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    from sphinx.ext.apidoc._extension import run_apidoc
+
+    # Require autodoc
+    app.setup_extension('sphinx.ext.autodoc')
+
+    # Configuration values
+    app.add_config_value(
+        'apidoc_exclude_patterns', (), 'env', types=frozenset({list, tuple})
+    )
+    app.add_config_value('apidoc_max_depth', 4, 'env', types=frozenset({int}))
+    app.add_config_value('apidoc_follow_links', False, 'env', types=frozenset({bool}))
+    app.add_config_value(
+        'apidoc_separate_modules', False, 'env', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'apidoc_include_private', False, 'env', types=frozenset({bool})
+    )
+    app.add_config_value('apidoc_no_headings', False, 'env', types=frozenset({bool}))
+    app.add_config_value('apidoc_module_first', False, 'env', types=frozenset({bool}))
+    app.add_config_value(
+        'apidoc_implicit_namespaces', False, 'env', types=frozenset({bool})
+    )
+    app.add_config_value(
+        'apidoc_automodule_options',
+        frozenset(('members', 'undoc-members', 'show-inheritance')),
+        'env',
+        types=frozenset({frozenset, list, set, tuple}),
+    )
+    app.add_config_value('apidoc_modules', (), 'env', types=frozenset({list, tuple}))
+
+    # Entry point to run apidoc
+    app.connect('builder-inited', run_apidoc)
+
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinx/ext/apidoc/__main__.py

@@ -0,0 +1,9 @@
+"""Command-line interface for the apidoc extension."""
+
+from __future__ import annotations
+
+import sys
+
+from sphinx.ext.apidoc._cli import main
+
+raise SystemExit(main(sys.argv[1:]))