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

sphinx/environment/collectors/toctree.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, TypeVar, cast
 from docutils import nodes
 
 from sphinx import addnodes
+from sphinx.domains.std import StandardDomain
 from sphinx.environment.adapters.toctree import note_toctree
 from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.locale import __
@@ -42,8 +43,13 @@ class TocTreeCollector(EnvironmentCollector):
             if not fnset:
                 del env.files_to_rebuild[subfn]
 
-    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.tocs[docname] = other.tocs[docname]
             env.toc_num_entries[docname] = other.toc_num_entries[docname]
@@ -83,8 +89,13 @@ class TocTreeCollector(EnvironmentCollector):
                     # make these nodes:
                     # list_item -> compact_paragraph -> reference
                     reference = nodes.reference(
-                        '', '', internal=True, refuri=docname,
-                        anchorname=anchorname, *nodetext)
+                        '',
+                        '',
+                        internal=True,
+                        refuri=docname,
+                        anchorname=anchorname,
+                        *nodetext,
+                    )
                     para = addnodes.compact_paragraph('', '', reference)
                     item: Element = nodes.list_item('', para)
                     sub_item = build_toc(sectionnode, depth + 1)
@@ -135,15 +146,23 @@ class TocTreeCollector(EnvironmentCollector):
                                 anchorname = _make_anchor_name(ids, numentries)
 
                                 reference = nodes.reference(
-                                    '', '', nodes.literal('', sig_node['_toc_name']),
-                                    internal=True, refuri=docname, anchorname=anchorname)
-                                para = addnodes.compact_paragraph('', '', reference,
-                                                                  skip_section_number=True)
+                                    '',
+                                    '',
+                                    nodes.literal('', sig_node['_toc_name']),
+                                    internal=True,
+                                    refuri=docname,
+                                    anchorname=anchorname,
+                                )
+                                para = addnodes.compact_paragraph(
+                                    '', '', reference, skip_section_number=True
+                                )
                                 entry = nodes.list_item('', para)
 
                                 # Find parent node
                                 parent = sig_node.parent
-                                while parent not in memo_parents and parent != sectionnode:
+                                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.
@@ -230,14 +249,21 @@ class TocTreeCollector(EnvironmentCollector):
         def _walk_toctree(toctreenode: addnodes.toctree, depth: int) -> None:
             if depth == 0:
                 return
-            for (_title, ref) in toctreenode['entries']:
+            for _title, ref in toctreenode['entries']:
                 if url_re.match(ref) or ref == 'self':
                     # don't mess with those
                     continue
                 if ref in assigned:
-                    logger.warning(__('%s is already assigned section numbers '
-                                      '(nested numbered toctree?)'), ref,
-                                   location=toctreenode, type='toc', subtype='secnum')
+                    logger.warning(
+                        __(
+                            '%s is already assigned section numbers '
+                            '(nested numbered toctree?)'
+                        ),
+                        ref,
+                        location=toctreenode,
+                        type='toc',
+                        subtype='secnum',
+                    )
                 elif ref in env.tocs:
                     secnums: dict[str, tuple[int, ...]] = {}
                     env.toc_secnumbers[ref] = secnums
@@ -260,7 +286,7 @@ class TocTreeCollector(EnvironmentCollector):
 
     def assign_figure_numbers(self, env: BuildEnvironment) -> list[str]:
         """Assign a figure number to each figure under a numbered toctree."""
-        generated_docnames = frozenset(env.domains['std']._virtual_doc_names)
+        generated_docnames = frozenset(env.domains.standard_domain._virtual_doc_names)
 
         rewrite_needed = []
 
@@ -270,10 +296,11 @@ class TocTreeCollector(EnvironmentCollector):
         fignum_counter: dict[str, dict[tuple[int, ...], int]] = {}
 
         def get_figtype(node: Node) -> str | None:
-            for domain in env.domains.values():
+            for domain in env.domains.sorted():
                 figtype = domain.get_enumerable_node_type(node)
-                if (domain.name == 'std'
-                        and not domain.get_numfig_title(node)):  # type: ignore[attr-defined]  # NoQA: E501
+                if isinstance(domain, StandardDomain) and not domain.get_numfig_title(
+                    node
+                ):
                     # Skip if uncaptioned node
                     continue
 
@@ -292,22 +319,27 @@ class TocTreeCollector(EnvironmentCollector):
 
             return secnum or ()
 
-        def get_next_fignumber(figtype: str, secnum: tuple[int, ...]) -> tuple[int, ...]:
+        def get_next_fignumber(
+            figtype: str, secnum: tuple[int, ...]
+        ) -> tuple[int, ...]:
             counter = fignum_counter.setdefault(figtype, {})
 
-            secnum = secnum[:env.config.numfig_secnum_depth]
+            secnum = secnum[: env.config.numfig_secnum_depth]
             counter[secnum] = counter.get(secnum, 0) + 1
             return (*secnum, counter[secnum])
 
-        def register_fignumber(docname: str, secnum: tuple[int, ...],
-                               figtype: str, fignode: Element) -> None:
+        def register_fignumber(
+            docname: str, secnum: tuple[int, ...], figtype: str, fignode: Element
+        ) -> None:
             env.toc_fignumbers.setdefault(docname, {})
             fignumbers = env.toc_fignumbers[docname].setdefault(figtype, {})
             figure_id = fignode['ids'][0]
 
             fignumbers[figure_id] = get_next_fignumber(figtype, secnum)
 
-        def _walk_doctree(docname: str, doctree: Element, secnum: tuple[int, ...]) -> None:
+        def _walk_doctree(
+            docname: str, doctree: Element, secnum: tuple[int, ...]
+        ) -> None:
             nonlocal generated_docnames
             for subnode in doctree.children:
                 if isinstance(subnode, nodes.section):

sphinx/errors.py

@@ -45,7 +45,10 @@ class ExtensionError(SphinxError):
     """Extension error."""
 
     def __init__(
-        self, message: str, orig_exc: Exception | None = None, modname: str | None = None
+        self,
+        message: str,
+        orig_exc: Exception | None = None,
+        modname: str | None = None,
     ) -> None:
         super().__init__(message)
         self.message = message

sphinx/events.py

@@ -5,10 +5,9 @@ Gracefully adapted from the TextPress system by Armin.
 
 from __future__ import annotations
 
-import contextlib
 from collections import defaultdict
 from operator import attrgetter
-from typing import TYPE_CHECKING, Any, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple, overload
 
 from sphinx.errors import ExtensionError, SphinxError
 from sphinx.locale import __
@@ -16,9 +15,20 @@ from sphinx.util import logging
 from sphinx.util.inspect import safe_getattr
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Callable, Iterable, Sequence, Set
+    from pathlib import Path
+    from typing import Any, Literal
 
+    from docutils import nodes
+
+    from sphinx import addnodes
     from sphinx.application import Sphinx
+    from sphinx.builders import Builder
+    from sphinx.config import Config
+    from sphinx.domains import Domain
+    from sphinx.environment import BuildEnvironment
+    from sphinx.ext.autodoc import _AutodocProcessDocstringListener
+    from sphinx.ext.todo import todo_node
 
 
 logger = logging.getLogger(__name__)
@@ -67,6 +77,293 @@ class EventManager:
             raise ExtensionError(__('Event %r already present') % name)
         self.events[name] = ''
 
+    # ---- Core events -------------------------------------------------------
+
+    @overload
+    def connect(
+        self,
+        name: Literal['config-inited'],
+        callback: Callable[[Sphinx, Config], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['builder-inited'],
+        callback: Callable[[Sphinx], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-get-outdated'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-before-read-docs'],
+        callback: Callable[[Sphinx, BuildEnvironment, list[str]], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-purge-doc'],
+        callback: Callable[[Sphinx, BuildEnvironment, str], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['source-read'],
+        callback: Callable[[Sphinx, str, list[str]], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['include-read'],
+        callback: Callable[[Sphinx, Path, str, list[str]], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['doctree-read'],
+        callback: Callable[[Sphinx, nodes.document], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-merge-info'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, list[str], BuildEnvironment], None
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-updated'],
+        callback: Callable[[Sphinx, BuildEnvironment], str],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-get-updated'],
+        callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['env-check-consistency'],
+        callback: Callable[[Sphinx, BuildEnvironment], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['write-started'],
+        callback: Callable[[Sphinx, Builder], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['doctree-resolved'],
+        callback: Callable[[Sphinx, nodes.document, str], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['missing-reference'],
+        callback: Callable[
+            [Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement],
+            nodes.reference | None,
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['warn-missing-reference'],
+        callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['build-finished'],
+        callback: Callable[[Sphinx, Exception | None], None],
+        priority: int,
+    ) -> int: ...
+
+    # ---- Events from builtin builders --------------------------------------
+
+    @overload
+    def connect(
+        self,
+        name: Literal['html-collect-pages'],
+        callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['html-page-context'],
+        callback: Callable[
+            [Sphinx, str, str, dict[str, Any], nodes.document], str | None
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['linkcheck-process-uri'],
+        callback: Callable[[Sphinx, str], str | None],
+        priority: int,
+    ) -> int: ...
+
+    # ---- Events from builtin extensions-- ----------------------------------
+
+    @overload
+    def connect(
+        self,
+        name: Literal['object-description-transform'],
+        callback: Callable[[Sphinx, str, str, addnodes.desc_content], None],
+        priority: int,
+    ) -> int: ...
+
+    # ---- Events from first-party extensions --------------------------------
+
+    @overload
+    def connect(
+        self,
+        name: Literal['autodoc-process-docstring'],
+        callback: _AutodocProcessDocstringListener,
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['autodoc-before-process-signature'],
+        callback: Callable[[Sphinx, Any, bool], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['autodoc-process-signature'],
+        callback: Callable[
+            [
+                Sphinx,
+                Literal[
+                    'module', 'class', 'exception', 'function', 'method', 'attribute'
+                ],
+                str,
+                Any,
+                dict[str, bool],
+                str | None,
+                str | None,
+            ],
+            tuple[str | None, str | None] | None,
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['autodoc-process-bases'],
+        callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['autodoc-skip-member'],
+        callback: Callable[
+            [
+                Sphinx,
+                Literal[
+                    'module', 'class', 'exception', 'function', 'method', 'attribute'
+                ],
+                str,
+                Any,
+                bool,
+                dict[str, bool],
+            ],
+            bool,
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['todo-defined'],
+        callback: Callable[[Sphinx, todo_node], None],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['viewcode-find-source'],
+        callback: Callable[
+            [Sphinx, str],
+            tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]],
+        ],
+        priority: int,
+    ) -> int: ...
+
+    @overload
+    def connect(
+        self,
+        name: Literal['viewcode-follow-imported'],
+        callback: Callable[[Sphinx, str, str], str | None],
+        priority: int,
+    ) -> int: ...
+
+    # ---- Catch-all ---------------------------------------------------------
+
+    @overload
+    def connect(
+        self,
+        name: str,
+        callback: Callable[..., Any],
+        priority: int,
+    ) -> int: ...
+
     def connect(self, name: str, callback: Callable, priority: int) -> int:
         """Connect a handler to specific event."""
         if name not in self.events:
@@ -85,13 +382,20 @@ class EventManager:
                     listeners.remove(listener)
 
     def emit(
-        self, name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()
+        self,
+        name: str,
+        *args: Any,
+        allowed_exceptions: tuple[type[Exception], ...] = (),
     ) -> list:
         """Emit a Sphinx event."""
         # not every object likes to be repr()'d (think
         # random stuff coming via autodoc)
-        with contextlib.suppress(Exception):
-            logger.debug('[app] emitting event: %r%s', name, repr(args)[:100])
+        try:
+            repr_args = repr(args)
+        except Exception:
+            pass
+        else:
+            logger.debug('[app] emitting event: %r%s', name, repr_args)
 
         results = []
         listeners = sorted(self.listeners[name], key=attrgetter('priority'))
@@ -117,7 +421,10 @@ class EventManager:
         return results
 
     def emit_firstresult(
-        self, name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()
+        self,
+        name: str,
+        *args: Any,
+        allowed_exceptions: tuple[type[Exception], ...] = (),
     ) -> Any:
         """Emit a Sphinx event and returns first result.
 

sphinx/ext/apidoc.py

@@ -69,7 +69,7 @@ def module_join(*modnames: str | None) -> str:
 
 def is_packagedir(dirname: str | None = None, files: list[str] | None = None) -> bool:
     """Check given *files* contains __init__ file."""
-    if files is dirname is None:
+    if files is None and dirname is None:
         return False
 
     if files is None:
@@ -96,7 +96,10 @@ def write_file(name: str, text: str, opts: CliOptions) -> Path:
 
 
 def create_module_file(
-    package: str | None, basename: str, opts: CliOptions, user_template_dir: str | None = None
+    package: str | None,
+    basename: str,
+    opts: CliOptions,
+    user_template_dir: str | None = None,
 ) -> Path:
     """Build the text of the file and write the file."""
     options = copy(OPTIONS)
@@ -148,7 +151,9 @@ def create_package_file(
         if not is_skipped_module(Path(root, sub), opts, excludes) and not is_initpy(sub)
     ]
     submodules = sorted(set(submodules))
-    submodules = [module_join(master_package, subroot, modname) for modname in submodules]
+    submodules = [
+        module_join(master_package, subroot, modname) for modname in submodules
+    ]
     options = copy(OPTIONS)
     if opts.includeprivate and 'private-members' not in options:
         options.append('private-members')
@@ -316,7 +321,9 @@ def recurse_tree(
         if is_pkg or is_namespace:
             # we are in a package with something to document
             if subs or len(files) > 1 or not is_skipped_package(root, opts):
-                subpackage = root[len(rootpath) :].lstrip(path.sep).replace(path.sep, '.')
+                subpackage = (
+                    root[len(rootpath) :].lstrip(path.sep).replace(path.sep, '.')
+                )
                 # if this is not a namespace or
                 # a namespace and there is something there to document
                 if not is_namespace or has_child_module(root, excludes, opts):
@@ -342,7 +349,9 @@ def recurse_tree(
                 if not is_skipped_module(Path(rootpath, py_file), opts, excludes):
                     module = py_file.split('.')[0]
                     written_files.append(
-                        create_module_file(root_package, module, opts, user_template_dir)
+                        create_module_file(
+                            root_package, module, opts, user_template_dir
+                        )
                     )
                     toplevels.append(module)
 
@@ -361,7 +370,7 @@ def is_excluded(root: str | Path, excludes: Sequence[re.Pattern[str]]) -> bool:
 
 def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        usage='%(prog)s [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> ' '[EXCLUDE_PATTERN, ...]',
+        usage='%(prog)s [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]',
         epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
         description=__("""
 Look recursively in <MODULE_PATH> for Python modules and packages and create
@@ -384,7 +393,9 @@ Note: By default this script will not overwrite already created files."""),
     parser.add_argument(
         'exclude_pattern',
         nargs='*',
-        help=__('fnmatch-style file and/or directory patterns ' 'to exclude from generation'),
+        help=__(
+            'fnmatch-style file and/or directory patterns to exclude from generation'
+        ),
     )
 
     parser.add_argument(
@@ -408,10 +419,14 @@ Note: By default this script will not overwrite already created files."""),
         dest='maxdepth',
         type=int,
         default=4,
-        help=__('maximum depth of submodules to show in the TOC ' '(default: 4)'),
+        help=__('maximum depth of submodules to show in the TOC (default: 4)'),
     )
     parser.add_argument(
-        '-f', '--force', action='store_true', dest='force', help=__('overwrite existing files')
+        '-f',
+        '--force',
+        action='store_true',
+        dest='force',
+        help=__('overwrite existing files'),
     )
     parser.add_argument(
         '-l',
@@ -420,7 +435,7 @@ Note: By default this script will not overwrite already created files."""),
         dest='followlinks',
         default=False,
         help=__(
-            'follow symbolic links. Powerful when combined ' 'with collective.recipe.omelette.'
+            'follow symbolic links. Powerful when combined with collective.recipe.omelette.'
         ),
     )
     parser.add_argument(
@@ -474,14 +489,14 @@ Note: By default this script will not overwrite already created files."""),
         '--module-first',
         action='store_true',
         dest='modulefirst',
-        help=__('put module documentation before submodule ' 'documentation'),
+        help=__('put module documentation before submodule documentation'),
     )
     parser.add_argument(
         '--implicit-namespaces',
         action='store_true',
         dest='implicit_namespaces',
         help=__(
-            'interpret module paths according to PEP-0420 ' 'implicit namespaces specification'
+            'interpret module paths according to PEP-0420 implicit namespaces specification'
         ),
     )
     parser.add_argument(
@@ -497,7 +512,9 @@ Note: By default this script will not overwrite already created files."""),
         '--remove-old',
         action='store_true',
         dest='remove_old',
-        help=__('Remove existing files in the output directory that were not generated'),
+        help=__(
+            'Remove existing files in the output directory that were not generated'
+        ),
     )
     exclusive_group.add_argument(
         '-F',
@@ -539,7 +556,9 @@ Note: By default this script will not overwrite already created files."""),
         '--doc-release',
         action='store',
         dest='release',
-        help=__('project release, used when --full is given, ' 'defaults to --doc-version'),
+        help=__(
+            'project release, used when --full is given, defaults to --doc-version'
+        ),
     )
 
     group = parser.add_argument_group(__('extension options'))
@@ -614,8 +633,7 @@ def main(argv: Sequence[str] = (), /) -> int:
 
     if args.header is None:
         args.header = rootpath.split(path.sep)[-1]
-    if args.suffix.startswith('.'):
-        args.suffix = args.suffix[1:]
+    args.suffix = args.suffix.removeprefix('.')
     if not Path(rootpath).is_dir():
         logger.error(__('%s is not a directory.'), rootpath)
         raise SystemExit(1)
@@ -649,7 +667,11 @@ def main(argv: Sequence[str] = (), /) -> int:
             'suffix': '.' + args.suffix,
             'master': 'index',
             'epub': True,
-            'extensions': ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.todo'],
+            'extensions': [
+                'sphinx.ext.autodoc',
+                'sphinx.ext.viewcode',
+                'sphinx.ext.todo',
+            ],
             'makefile': True,
             'batchfile': True,
             'make_mode': True,
@@ -670,7 +692,9 @@ def main(argv: Sequence[str] = (), /) -> int:
                 d['extensions'].extend(ext.split(','))
 
         if not args.dryrun:
-            qs.generate(d, silent=True, overwrite=args.force, templatedir=args.templatedir)
+            qs.generate(
+                d, silent=True, overwrite=args.force, templatedir=args.templatedir
+            )
     elif args.tocfile:
         written_files.append(
             create_modules_toc_file(modules, args, args.tocfile, args.templatedir)