Sphinx 8.2.0rc1__py3-none-any.whl → 8.2.1__py3-none-any.whl

sphinx/ext/apidoc/_generate.py

@@ -63,8 +63,8 @@ def is_package_dir(
 
 def write_file(name: str, text: str, opts: ApidocOptions) -> Path:
     """Write the output file for module/package <name>."""
-    fname = Path(opts.destdir, f'{name}.{opts.suffix}')
-    if opts.dryrun:
+    fname = Path(opts.dest_dir, f'{name}.{opts.suffix}')
+    if opts.dry_run:
         if not opts.quiet:
             LOGGER.info(__('Would create file %s.'), fname)
         return fname
@@ -87,12 +87,12 @@ def create_module_file(
 ) -> Path:
     """Build the text of the file and write the file."""
     options = set(OPTIONS if not opts.automodule_options else opts.automodule_options)
-    if opts.includeprivate:
+    if opts.include_private:
         options.add('private-members')
 
     qualname = module_join(package, basename)
     context = {
-        'show_headings': not opts.noheadings,
+        'show_headings': not opts.no_headings,
         'basename': basename,
         'qualname': qualname,
         'automodule_options': sorted(options),
@@ -140,7 +140,7 @@ def create_package_file(
         module_join(master_package, subroot, modname) for modname in submodules
     ]
     options = OPTIONS.copy()
-    if opts.includeprivate:
+    if opts.include_private:
         options.add('private-members')
 
     pkgname = module_join(master_package, subroot)
@@ -149,11 +149,11 @@ def create_package_file(
         'subpackages': subpackages,
         'submodules': submodules,
         'is_namespace': is_namespace,
-        'modulefirst': opts.modulefirst,
-        'separatemodules': opts.separatemodules,
+        'modulefirst': opts.module_first,
+        'separatemodules': opts.separate_modules,
         'automodule_options': sorted(options),
-        'show_headings': not opts.noheadings,
-        'maxdepth': opts.maxdepth,
+        'show_headings': not opts.no_headings,
+        'maxdepth': opts.max_depth,
     }
     if user_template_dir is not None:
         template_path = [user_template_dir, template_dir]
@@ -165,7 +165,7 @@ def create_package_file(
     text = ReSTRenderer(template_path).render('package.rst.jinja', context)
     written.append(write_file(pkgname, text, opts))
 
-    if submodules and opts.separatemodules:
+    if submodules and opts.separate_modules:
         written.extend([
             create_module_file(None, submodule, opts, user_template_dir)
             for submodule in submodules
@@ -192,7 +192,7 @@ def create_modules_toc_file(
 
     context = {
         'header': opts.header,
-        'maxdepth': opts.maxdepth,
+        'maxdepth': opts.max_depth,
         'docnames': modules,
     }
     template_path: Sequence[str | os.PathLike[str]]
@@ -230,7 +230,7 @@ def is_skipped_module(
         # skip if the file doesn't exist
         return True
     # skip if the module has a "private" name
-    return filename.name.startswith('_') and not opts.includeprivate
+    return filename.name.startswith('_') and not opts.include_private
 
 
 def walk(
@@ -239,7 +239,7 @@ def walk(
     opts: ApidocOptions,
 ) -> Iterator[tuple[str, list[str], list[str]]]:
     """Walk through the directory and list files and subdirectories up."""
-    for root, subs, files in os.walk(root_path, followlinks=opts.followlinks):
+    for root, subs, files in os.walk(root_path, followlinks=opts.follow_links):
         # document only Python module files (that aren't excluded)
         files = sorted(
             f
@@ -249,7 +249,7 @@ def walk(
 
         # remove hidden ('.') and private ('_') directories, as well as
         # excluded dirs
-        if opts.includeprivate:
+        if opts.include_private:
             exclude_prefixes: tuple[str, ...] = ('.',)
         else:
             exclude_prefixes = ('.', '_')

sphinx/ext/apidoc/_shared.py

@@ -7,18 +7,20 @@ from sphinx.locale import __
 from sphinx.util import logging
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Sequence, Set
     from pathlib import Path
-    from typing import Final
+    from typing import Final, Self
+
+    from sphinx.config import Config
 
 LOGGER: Final[logging.SphinxLoggerAdapter] = logging.getLogger('sphinx.ext.apidoc')
 
 
 def _remove_old_files(
-    written_files: Sequence[Path], destdir: Path, suffix: str
+    written_files: Sequence[Path], dest_dir: Path, suffix: str
 ) -> None:
     files_to_keep = frozenset(written_files)
-    for existing in destdir.rglob(f'*.{suffix}'):
+    for existing in dest_dir.rglob(f'*.{suffix}'):
         if existing not in files_to_keep:
             try:
                 existing.unlink()
@@ -35,25 +37,26 @@ def _remove_old_files(
 class ApidocOptions:
     """Options for apidoc."""
 
+    dest_dir: Path
     module_path: Path
-    destdir: Path
 
     exclude_pattern: Sequence[str] = ()
-    quiet: bool = False
-    maxdepth: int = 4
-    force: bool = False
-    followlinks: bool = False
-    dryrun: bool = False
-    separatemodules: bool = False
-    includeprivate: bool = False
-    tocfile: str = 'modules'
-    noheadings: bool = False
-    modulefirst: bool = False
+    max_depth: int = 4
+    follow_links: bool = False
+    separate_modules: bool = False
+    include_private: bool = False
+    toc_file: str = 'modules'
+    no_headings: bool = False
+    module_first: bool = False
     implicit_namespaces: bool = False
-    automodule_options: set[str] = dataclasses.field(default_factory=set)
+    automodule_options: Set[str] = dataclasses.field(default_factory=set)
     suffix: str = 'rst'
 
-    remove_old: bool = False
+    remove_old: bool = True
+
+    quiet: bool = False
+    dry_run: bool = False
+    force: bool = True
 
     # --full only
     full: bool = False
@@ -63,4 +66,34 @@ class ApidocOptions:
     version: str | None = None
     release: str | None = None
     extensions: Sequence[str] | None = None
-    templatedir: str | None = None
+    template_dir: str | None = None
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class ApidocDefaults:
+    """Default values for apidoc options."""
+
+    exclude_patterns: list[str]
+    automodule_options: frozenset[str]
+    max_depth: int
+    follow_links: bool
+    separate_modules: bool
+    include_private: bool
+    no_headings: bool
+    module_first: bool
+    implicit_namespaces: bool
+
+    @classmethod
+    def from_config(cls, config: Config, /) -> Self:
+        """Collect the default values for apidoc options."""
+        return cls(
+            exclude_patterns=config.apidoc_exclude_patterns,
+            automodule_options=frozenset(config.apidoc_automodule_options),
+            max_depth=config.apidoc_max_depth,
+            follow_links=config.apidoc_follow_links,
+            separate_modules=config.apidoc_separate_modules,
+            include_private=config.apidoc_include_private,
+            no_headings=config.apidoc_no_headings,
+            module_first=config.apidoc_module_first,
+            implicit_namespaces=config.apidoc_implicit_namespaces,
+        )

sphinx/ext/autodoc/__init__.py

@@ -291,7 +291,7 @@ def between(
 # This class is used only in ``sphinx.ext.autodoc.directive``,
 # But we define this class here to keep compatibility
 # See: https://github.com/sphinx-doc/sphinx/issues/4538
-class Options(dict[str, Any]):
+class Options(dict[str, Any]):  # NoQA: FURB189
     """A dict/attribute hybrid that returns None on nonexisting keys."""
 
     def copy(self) -> Options:
@@ -381,7 +381,7 @@ class Documenter:
 
     def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
         """getattr() override for types such as Zope interfaces."""
-        return autodoc_attrgetter(self.env._registry, obj, name, *defargs)
+        return autodoc_attrgetter(obj, name, *defargs, registry=self.env._registry)
 
     @classmethod
     def can_document_member(
@@ -3139,7 +3139,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
 
 
 def autodoc_attrgetter(
-    registry: SphinxComponentRegistry, obj: Any, name: str, *defargs: Any
+    obj: Any, name: str, *defargs: Any, registry: SphinxComponentRegistry
 ) -> Any:
     """Alternative getattr() for types"""
     for typ, func in registry.autodoc_attrgetters.items():

sphinx/ext/autodoc/directive.py

@@ -52,7 +52,7 @@ AUTODOC_EXTENDABLE_OPTIONS = frozenset({
 })
 
 
-class DummyOptionSpec(dict[str, Callable[[str], str]]):
+class DummyOptionSpec(dict[str, Callable[[str], str]]):  # NoQA: FURB189
     """An option_spec allows any options."""
 
     def __bool__(self) -> bool:

sphinx/ext/autodoc/mock.py

@@ -30,7 +30,7 @@ class _MockObject:
     __sphinx_mock__ = True
     __sphinx_decorator_args__: tuple[Any, ...] = ()
 
-    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
+    def __new__(cls, *args: Any, **kwargs: Any) -> Any:  # NoQA: ARG004
         if len(args) == 3 and isinstance(args[1], tuple):
             superclass = args[1][-1].__class__
             if superclass is cls:

sphinx/ext/autosummary/__init__.py

@@ -180,6 +180,17 @@ class FakeDirective(DocumenterBridge):
         super().__init__(env, None, Options(), 0, state)
 
 
+def get_documenter(app: Sphinx, obj: Any, parent: Any) -> type[Documenter]:
+    """Get an autodoc.Documenter class suitable for documenting the given
+    object.
+
+    *obj* is the Python object to be documented, and *parent* is an
+    another Python object (e.g. a module or a class) to which *obj*
+    belongs to.
+    """
+    return _get_documenter(obj, parent, registry=app.registry)
+
+
 def _get_documenter(
     obj: Any, parent: Any, *, registry: SphinxComponentRegistry
 ) -> type[Documenter]:

sphinx/ext/napoleon/__init__.py

@@ -11,6 +11,7 @@ from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
 from sphinx.util import inspect
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence, Set
     from typing import Any
 
     from sphinx.config import _ConfigRebuild
@@ -270,27 +271,27 @@ class Config:
 
     """
 
-    _config_values: dict[str, tuple[Any, _ConfigRebuild]] = {
-        'napoleon_google_docstring': (True, 'env'),
-        'napoleon_numpy_docstring': (True, 'env'),
-        'napoleon_include_init_with_doc': (False, 'env'),
-        'napoleon_include_private_with_doc': (False, 'env'),
-        'napoleon_include_special_with_doc': (False, 'env'),
-        'napoleon_use_admonition_for_examples': (False, 'env'),
-        'napoleon_use_admonition_for_notes': (False, 'env'),
-        'napoleon_use_admonition_for_references': (False, 'env'),
-        'napoleon_use_ivar': (False, 'env'),
-        'napoleon_use_param': (True, 'env'),
-        'napoleon_use_rtype': (True, 'env'),
-        'napoleon_use_keyword': (True, 'env'),
-        'napoleon_preprocess_types': (False, 'env'),
-        'napoleon_type_aliases': (None, 'env'),
-        'napoleon_custom_sections': (None, 'env'),
-        'napoleon_attr_annotations': (True, 'env'),
-    }
+    _config_values: Sequence[tuple[str, bool | None, _ConfigRebuild, Set[type]]] = (
+        ('napoleon_google_docstring', True, 'env', frozenset({bool})),
+        ('napoleon_numpy_docstring', True, 'env', frozenset({bool})),
+        ('napoleon_include_init_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_include_private_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_include_special_with_doc', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_examples', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_notes', False, 'env', frozenset({bool})),
+        ('napoleon_use_admonition_for_references', False, 'env', frozenset({bool})),
+        ('napoleon_use_ivar', False, 'env', frozenset({bool})),
+        ('napoleon_use_param', True, 'env', frozenset({bool})),
+        ('napoleon_use_rtype', True, 'env', frozenset({bool})),
+        ('napoleon_use_keyword', True, 'env', frozenset({bool})),
+        ('napoleon_preprocess_types', False, 'env', frozenset({bool})),
+        ('napoleon_type_aliases', None, 'env', frozenset({dict, NoneType})),
+        ('napoleon_custom_sections', None, 'env', frozenset({list, tuple, NoneType})),
+        ('napoleon_attr_annotations', True, 'env', frozenset({bool})),
+    )
 
     def __init__(self, **settings: Any) -> None:
-        for name, (default, _rebuild) in self._config_values.items():
+        for name, default, _rebuild, _types in self._config_values:
             setattr(self, name, default)
         for name, value in settings.items():
             setattr(self, name, value)
@@ -331,11 +332,9 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('autodoc-process-docstring', _process_docstring)
     app.connect('autodoc-skip-member', _skip_member)
 
-    for name, (default, rebuild) in Config._config_values.items():
-        if isinstance(default, bool):
-            app.add_config_value(name, default, rebuild, types=frozenset({bool}))
-        else:
-            app.add_config_value(name, default, rebuild, types=frozenset({NoneType}))
+    for name, default, rebuild, types in Config._config_values:
+        app.add_config_value(name, default, rebuild, types=types)
+
     return {
         'version': sphinx.__display_version__,
         'parallel_read_safe': True,

sphinx/ext/viewcode.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-import importlib.util
+import importlib
 import operator
 import posixpath
 import traceback
@@ -62,16 +62,20 @@ def _get_full_modname(modname: str, attribute: str) -> str | None:
         num_parts = len(module_path)
         for i in range(num_parts, 0, -1):
             mod_root = '.'.join(module_path[:i])
-            module_spec = importlib.util.find_spec(mod_root)
-            if module_spec is not None:
+            try:
+                # import_module() caches the module in sys.modules
+                module = importlib.import_module(mod_root)
                 break
+            except ModuleNotFoundError:
+                continue
+            except BaseException as exc:
+                # Importing modules may cause any side effects, including
+                # SystemExit, so we need to catch all errors.
+                msg = f"viewcode failed to import '{mod_root}'."
+                raise ImportError(msg) from exc
         else:
             return None
-        # Load and execute the module
-        module = importlib.util.module_from_spec(module_spec)
-        if module_spec.loader is None:
-            return None
-        module_spec.loader.exec_module(module)
+
         if i != num_parts:
             for mod in module_path[i:]:
                 module = getattr(module, mod)

sphinx/highlighting.py

@@ -171,7 +171,7 @@ class PygmentsBridge:
                     lang,
                     location=location,
                     type='misc',
-                    subtype='higlighting_failure',
+                    subtype='highlighting_failure',
                 )
                 lexer = lexer_classes['none'](**opts)