Sphinx 8.2.0rc1__py3-none-any.whl → 8.2.0rc2__py3-none-any.whl

sphinx/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = '8.2.0rc1'
+__version__ = '8.2.0rc2'
 __display_version__ = __version__  # used for command line version
 
 # Keep this file executable as-is in Python 3!
@@ -34,7 +34,7 @@ warnings.filterwarnings(
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 2, 0, 'candidate', 1)
+version_info = (8, 2, 0, 'candidate', 2)
 
 package_dir = _StrPath(__file__).resolve().parent
 

sphinx/application.py

@@ -1116,7 +1116,7 @@ class Sphinx:
         logger.debug('[app] adding directive: %r', (name, cls))
         if not override and docutils.is_directive_registered(name):
             logger.warning(
-                __('directive %r is already registered, it will be overridden'),
+                __('directive %r is already registered and will not be overridden'),
                 name,
                 type='app',
                 subtype='add_directive',
@@ -1142,7 +1142,7 @@ class Sphinx:
         logger.debug('[app] adding role: %r', (name, role))
         if not override and docutils.is_role_registered(name):
             logger.warning(
-                __('role %r is already registered, it will be overridden'),
+                __('role %r is already registered and will not be overridden'),
                 name,
                 type='app',
                 subtype='add_role',
@@ -1170,7 +1170,7 @@ class Sphinx:
         logger.debug('[app] adding generic role: %r', (name, nodeclass))
         if not override and docutils.is_role_registered(name):
             logger.warning(
-                __('role %r is already registered, it will be overridden'),
+                __('role %r is already registered and will not be overridden'),
                 name,
                 type='app',
                 subtype='add_generic_role',

sphinx/domains/math.py

@@ -49,6 +49,8 @@ class MathDomain(Domain):
 
     initial_data: dict[str, Any] = {
         'objects': {},  # labelid -> (docname, eqno)
+        # backwards compatibility
+        'has_equations': {},  # https://github.com/sphinx-doc/sphinx/issues/13346
     }
     dangling_warnings = {
         'eq': 'equation not found: %(target)s',

sphinx/domains/python/_annotations.py

@@ -12,6 +12,7 @@ from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.addnodes import pending_xref, pending_xref_condition
+from sphinx.locale import _
 from sphinx.pycode.parser import Token, TokenProcessor
 from sphinx.util.inspect import signature_from_str
 
@@ -479,19 +480,13 @@ def _parse_arglist(
     last_kind = None
     for param in sig.parameters.values():
         if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY:
-            # PEP-570: Separator for Positional Only Parameter: /
-            params += addnodes.desc_parameter(
-                '', '', addnodes.desc_sig_operator('', '/')
-            )
+            params += _positional_only_separator()
         if param.kind == param.KEYWORD_ONLY and last_kind in {
             param.POSITIONAL_OR_KEYWORD,
             param.POSITIONAL_ONLY,
             None,
         }:
-            # PEP-3102: Separator for Keyword Only Parameter: *
-            params += addnodes.desc_parameter(
-                '', '', addnodes.desc_sig_operator('', '*')
-            )
+            params += _keyword_only_separator()
 
         node = addnodes.desc_parameter()
         if param.kind == param.VAR_POSITIONAL:
@@ -523,12 +518,33 @@ def _parse_arglist(
         last_kind = param.kind
 
     if last_kind == Parameter.POSITIONAL_ONLY:
-        # PEP-570: Separator for Positional Only Parameter: /
-        params += addnodes.desc_parameter('', '', addnodes.desc_sig_operator('', '/'))
+        params += _positional_only_separator()
 
     return params
 
 
+def _positional_only_separator() -> addnodes.desc_parameter:
+    # PEP 570: Separator for positional only parameters: /
+    positional_only_abbr = nodes.abbreviation(
+        '/', '/', explanation=_('Positional-only parameter separator (PEP 570)')
+    )
+    positional_only_op = addnodes.desc_sig_operator(
+        '/', '', positional_only_abbr, classes=['positional-only-separator']
+    )
+    return addnodes.desc_parameter('/', '', positional_only_op)
+
+
+def _keyword_only_separator() -> addnodes.desc_parameter:
+    # PEP 3102: Separator for keyword only parameters: *
+    keyword_only_abbr = nodes.abbreviation(
+        '*', '*', explanation=_('Keyword-only parameters separator (PEP 3102)')
+    )
+    keyword_only_op = addnodes.desc_sig_operator(
+        '*', '', keyword_only_abbr, classes=['keyword-only-separator']
+    )
+    return addnodes.desc_parameter('*', '', keyword_only_op)
+
+
 def _pseudo_parse_arglist(
     signode: desc_signature,
     arglist: str,

sphinx/domains/python/_object.py

@@ -352,11 +352,14 @@ class PyObject(ObjectDescription[tuple[str, str]]):
                     multi_line_parameter_list,
                     trailing_comma,
                 )
-            except SyntaxError:
+            except SyntaxError as exc:
                 # fallback to parse arglist original parser
                 # (this may happen if the argument list is incorrectly used
                 # as a list of bases when documenting a class)
                 # it supports to represent optional arguments (ex. "func(foo [, bar])")
+                logger.debug(
+                    'syntax error in arglist (%r): %s', arglist, exc, location=signode
+                )
                 _pseudo_parse_arglist(
                     signode,
                     arglist,

sphinx/ext/apidoc/__init__.py

@@ -13,9 +13,54 @@ 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
 
-__all__: Sequence[str] = ('main',)
+    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/_cli.py

@@ -55,7 +55,7 @@ Note: By default this script will not overwrite already created files."""),
         '-o',
         '--output-dir',
         action='store',
-        dest='destdir',
+        dest='dest_dir',
         required=True,
         help=__('directory to place all output'),
     )
@@ -69,7 +69,7 @@ Note: By default this script will not overwrite already created files."""),
         '-d',
         '--maxdepth',
         action='store',
-        dest='maxdepth',
+        dest='max_depth',
         type=int,
         default=4,
         help=__('maximum depth of submodules to show in the TOC (default: 4)'),
@@ -85,7 +85,7 @@ Note: By default this script will not overwrite already created files."""),
         '-l',
         '--follow-links',
         action='store_true',
-        dest='followlinks',
+        dest='follow_links',
         default=False,
         help=__(
             'follow symbolic links. Powerful when combined with collective.recipe.omelette.'
@@ -95,27 +95,27 @@ Note: By default this script will not overwrite already created files."""),
         '-n',
         '--dry-run',
         action='store_true',
-        dest='dryrun',
+        dest='dry_run',
         help=__('run the script without creating files'),
     )
     parser.add_argument(
         '-e',
         '--separate',
         action='store_true',
-        dest='separatemodules',
+        dest='separate_modules',
         help=__('put documentation for each module on its own page'),
     )
     parser.add_argument(
         '-P',
         '--private',
         action='store_true',
-        dest='includeprivate',
+        dest='include_private',
         help=__('include "_private" modules'),
     )
     parser.add_argument(
         '--tocfile',
         action='store',
-        dest='tocfile',
+        dest='toc_file',
         default='modules',
         help=__('filename of table of contents (default: modules)'),
     )
@@ -123,14 +123,14 @@ Note: By default this script will not overwrite already created files."""),
         '-T',
         '--no-toc',
         action='store_false',
-        dest='tocfile',
+        dest='toc_file',
         help=__("don't create a table of contents file"),
     )
     parser.add_argument(
         '-E',
         '--no-headings',
         action='store_true',
-        dest='noheadings',
+        dest='no_headings',
         help=__(
             "don't create headings for the module/package "
             'packages (e.g. when the docstrings already '
@@ -141,7 +141,7 @@ Note: By default this script will not overwrite already created files."""),
         '-M',
         '--module-first',
         action='store_true',
-        dest='modulefirst',
+        dest='module_first',
         help=__('put module documentation before submodule documentation'),
     )
     parser.add_argument(
@@ -245,7 +245,7 @@ Note: By default this script will not overwrite already created files."""),
         '-t',
         '--templatedir',
         metavar='TEMPLATEDIR',
-        dest='templatedir',
+        dest='template_dir',
         help=__('template directory for template files'),
     )
 
@@ -264,17 +264,17 @@ def main(argv: Sequence[str] = (), /) -> int:
         for exclude in dict.fromkeys(opts.exclude_pattern)
     )
 
-    written_files, modules = recurse_tree(rootpath, excludes, opts, opts.templatedir)
+    written_files, modules = recurse_tree(rootpath, excludes, opts, opts.template_dir)
 
     if opts.full:
         _full_quickstart(opts, modules=modules)
-    elif opts.tocfile:
+    elif opts.toc_file:
         written_files.append(
-            create_modules_toc_file(modules, opts, opts.tocfile, opts.templatedir)
+            create_modules_toc_file(modules, opts, opts.toc_file, opts.template_dir)
         )
 
-    if opts.remove_old and not opts.dryrun:
-        _remove_old_files(written_files, opts.destdir, opts.suffix)
+    if opts.remove_old and not opts.dry_run:
+        _remove_old_files(written_files, opts.dest_dir, opts.suffix)
 
     return 0
 
@@ -286,7 +286,7 @@ def _parse_args(argv: Sequence[str], /) -> ApidocOptions:
     # normalise options
 
     args.module_path = root_path = Path(args.module_path).resolve()
-    args.destdir = Path(args.destdir)
+    args.dest_dir = Path(args.dest_dir)
     if not root_path.is_dir():
         LOGGER.error(__('%s is not a directory.'), root_path)
         raise SystemExit(1)
@@ -295,13 +295,13 @@ def _parse_args(argv: Sequence[str], /) -> ApidocOptions:
         args.header = root_path.name
     args.suffix = args.suffix.removeprefix('.')
 
-    if not args.dryrun:
-        ensuredir(args.destdir)
+    if not args.dry_run:
+        ensuredir(args.dest_dir)
 
     if not args.automodule_options:
-        args.automodule_options = set()
+        args.automodule_options = frozenset()
     elif isinstance(args.automodule_options, str):
-        args.automodule_options = set(args.automodule_options.split(','))
+        args.automodule_options = frozenset(args.automodule_options.split(','))
 
     return ApidocOptions(**args.__dict__)
 
@@ -318,7 +318,7 @@ def _full_quickstart(opts: ApidocOptions, /, *, modules: list[str]) -> None:
         prev_module = module
         text += f'   {module}\n'
     d: dict[str, Any] = {
-        'path': str(opts.destdir),
+        'path': str(opts.dest_dir),
         'sep': False,
         'dot': '_',
         'project': opts.header,
@@ -336,7 +336,7 @@ def _full_quickstart(opts: ApidocOptions, /, *, modules: list[str]) -> None:
         'makefile': True,
         'batchfile': True,
         'make_mode': True,
-        'mastertocmaxdepth': opts.maxdepth,
+        'mastertocmaxdepth': opts.max_depth,
         'mastertoctree': text,
         'language': 'en',
         'module_path': str(opts.module_path),
@@ -352,5 +352,5 @@ def _full_quickstart(opts: ApidocOptions, /, *, modules: list[str]) -> None:
             d['extensions'].remove(ext)
             d['extensions'].extend(ext.split(','))
 
-    if not opts.dryrun:
-        qs.generate(d, silent=True, overwrite=opts.force, templatedir=opts.templatedir)
+    if not opts.dry_run:
+        qs.generate(d, silent=True, overwrite=opts.force, templatedir=opts.template_dir)

sphinx/ext/apidoc/_extension.py

@@ -0,0 +1,262 @@
+"""Sphinx extension for auto-generating API documentation."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sphinx._cli.util.colour import bold
+from sphinx.ext.apidoc._generate import create_modules_toc_file, recurse_tree
+from sphinx.ext.apidoc._shared import (
+    LOGGER,
+    ApidocDefaults,
+    ApidocOptions,
+    _remove_old_files,
+)
+from sphinx.locale import __
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Sequence
+    from typing import Any
+
+    from sphinx.application import Sphinx
+
+_BOOL_KEYS = frozenset({
+    'follow_links',
+    'separate_modules',
+    'include_private',
+    'no_headings',
+    'module_first',
+    'implicit_namespaces',
+})
+_ALLOWED_KEYS = _BOOL_KEYS | frozenset({
+    'path',
+    'destination',
+    'exclude_patterns',
+    'automodule_options',
+    'max_depth',
+})
+
+
+def run_apidoc(app: Sphinx) -> None:
+    """Run the apidoc extension."""
+    defaults = ApidocDefaults.from_config(app.config)
+    apidoc_modules: Sequence[dict[str, Any]] = app.config.apidoc_modules
+    srcdir: Path = app.srcdir
+    confdir: Path = app.confdir
+
+    LOGGER.info(bold(__('Running apidoc')))
+
+    module_options: dict[str, Any]
+    for i, module_options in enumerate(apidoc_modules):
+        _run_apidoc_module(
+            i,
+            options=module_options,
+            defaults=defaults,
+            srcdir=srcdir,
+            confdir=confdir,
+        )
+
+
+def _run_apidoc_module(
+    i: int,
+    *,
+    options: dict[str, Any],
+    defaults: ApidocDefaults,
+    srcdir: Path,
+    confdir: Path,
+) -> None:
+    """Run apidoc for a single module."""
+    args = _parse_module_options(
+        i, options=options, defaults=defaults, srcdir=srcdir, confdir=confdir
+    )
+    if args is None:
+        return
+
+    exclude_patterns_compiled: list[re.Pattern[str]] = [
+        re.compile(fnmatch.translate(exclude)) for exclude in args.exclude_pattern
+    ]
+
+    written_files, modules = recurse_tree(
+        args.module_path, exclude_patterns_compiled, args, args.template_dir
+    )
+    if args.toc_file:
+        written_files.append(
+            create_modules_toc_file(modules, args, args.toc_file, args.template_dir)
+        )
+    if args.remove_old:
+        _remove_old_files(written_files, args.dest_dir, args.suffix)
+
+
+def _parse_module_options(
+    i: int,
+    *,
+    options: dict[str, Any],
+    defaults: ApidocDefaults,
+    srcdir: Path,
+    confdir: Path,
+) -> ApidocOptions | None:
+    if not isinstance(options, dict):
+        LOGGER.warning(__('apidoc_modules item %i must be a dict'), i, type='apidoc')
+        return None
+
+    # module path should be absolute or relative to the conf directory
+    try:
+        path = Path(options['path'])
+    except KeyError:
+        LOGGER.warning(
+            __("apidoc_modules item %i must have a 'path' key"), i, type='apidoc'
+        )
+        return None
+    except TypeError:
+        LOGGER.warning(
+            __("apidoc_modules item %i 'path' must be a string"), i, type='apidoc'
+        )
+        return None
+    module_path = confdir / path
+    if not module_path.is_dir():
+        LOGGER.warning(
+            __("apidoc_modules item %i 'path' is not an existing folder: %s"),
+            i,
+            module_path,
+            type='apidoc',
+        )
+        return None
+
+    # destination path should be relative to the source directory
+    try:
+        destination = Path(options['destination'])
+    except KeyError:
+        LOGGER.warning(
+            __("apidoc_modules item %i must have a 'destination' key"),
+            i,
+            type='apidoc',
+        )
+        return None
+    except TypeError:
+        LOGGER.warning(
+            __("apidoc_modules item %i 'destination' must be a string"),
+            i,
+            type='apidoc',
+        )
+        return None
+    if destination.is_absolute():
+        LOGGER.warning(
+            __("apidoc_modules item %i 'destination' should be a relative path"),
+            i,
+            type='apidoc',
+        )
+        return None
+    dest_path = srcdir / destination
+    try:
+        dest_path.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        LOGGER.warning(
+            __('apidoc_modules item %i cannot create destination directory: %s'),
+            i,
+            exc.strerror,
+            type='apidoc',
+        )
+        return None
+
+    # exclude patterns should be absolute or relative to the conf directory
+    exclude_patterns: list[str] = [
+        str(confdir / pattern)
+        for pattern in _check_collection_of_strings(
+            i, options, key='exclude_patterns', default=defaults.exclude_patterns
+        )
+    ]
+
+    # TODO template_dir
+
+    max_depth = defaults.max_depth
+    if 'max_depth' in options:
+        if not isinstance(options['max_depth'], int):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must be an int"),
+                i,
+                'max_depth',
+                type='apidoc',
+            )
+        else:
+            max_depth = options['max_depth']
+
+    bool_options: dict[str, bool] = {}
+    for key in sorted(_BOOL_KEYS):
+        if key not in options:
+            bool_options[key] = getattr(defaults, key)
+        elif not isinstance(options[key], bool):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must be a boolean"),
+                i,
+                key,
+                type='apidoc',
+            )
+            bool_options[key] = getattr(defaults, key)
+        else:
+            bool_options[key] = options[key]
+
+    # TODO per-module automodule_options
+    automodule_options = frozenset(
+        _check_collection_of_strings(
+            i, options, key='automodule_options', default=defaults.automodule_options
+        )
+    )
+
+    if diff := options.keys() - _ALLOWED_KEYS:
+        LOGGER.warning(
+            __('apidoc_modules item %i has unexpected keys: %s'),
+            i,
+            ', '.join(sorted(diff)),
+            type='apidoc',
+        )
+
+    return ApidocOptions(
+        dest_dir=dest_path,
+        module_path=module_path,
+        exclude_pattern=exclude_patterns,
+        automodule_options=automodule_options,
+        max_depth=max_depth,
+        quiet=True,
+        follow_links=bool_options['follow_links'],
+        separate_modules=bool_options['separate_modules'],
+        include_private=bool_options['include_private'],
+        no_headings=bool_options['no_headings'],
+        module_first=bool_options['module_first'],
+        implicit_namespaces=bool_options['implicit_namespaces'],
+    )
+
+
+def _check_collection_of_strings(
+    index: int,
+    options: dict[str, Any],
+    *,
+    key: str,
+    default: Collection[str],
+) -> Collection[str]:
+    """Check that a key's value is a collection of strings in the options.
+
+    :returns: The value of the key, or None if invalid.
+    """
+    if key not in options:
+        return default
+    if not isinstance(options[key], list | tuple | set | frozenset):
+        LOGGER.warning(
+            __("apidoc_modules item %i '%s' must be a sequence"),
+            index,
+            key,
+            type='apidoc',
+        )
+        return default
+    for item in options[key]:
+        if not isinstance(item, str):
+            LOGGER.warning(
+                __("apidoc_modules item %i '%s' must contain strings"),
+                index,
+                key,
+                type='apidoc',
+            )
+            return default
+    return options[key]

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

@@ -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/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/writers/html5.py

@@ -906,8 +906,8 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):  # type: ignore[misc]
 
     def visit_abbreviation(self, node: Element) -> None:
         attrs = {}
-        if node.hasattr('explanation'):
-            attrs['title'] = node['explanation']
+        if explanation := node.get('explanation', ''):
+            attrs['title'] = explanation
         self.body.append(self.starttag(node, 'abbr', '', **attrs))
 
     def depart_abbreviation(self, node: Element) -> None:

sphinx/writers/latex.py

@@ -2082,11 +2082,12 @@ class LaTeXTranslator(SphinxTranslator):
         self.body.append('}}')
 
     def visit_abbreviation(self, node: Element) -> None:
+        explanation = node.get('explanation', '')
         abbr = node.astext()
         self.body.append(r'\sphinxstyleabbreviation{')
         # spell out the explanation once
-        if node.hasattr('explanation') and abbr not in self.handled_abbrs:
-            self.context.append('} (%s)' % self.encode(node['explanation']))
+        if explanation and abbr not in self.handled_abbrs:
+            self.context.append('} (%s)' % self.encode(explanation))
             self.handled_abbrs.add(abbr)
         else:
             self.context.append('}')

sphinx/writers/texinfo.py

@@ -1537,10 +1537,11 @@ class TexinfoTranslator(SphinxTranslator):
         pass
 
     def visit_abbreviation(self, node: Element) -> None:
+        explanation = node.get('explanation', '')
         abbr = node.astext()
         self.body.append('@abbr{')
-        if node.hasattr('explanation') and abbr not in self.handled_abbrs:
-            self.context.append(',%s}' % self.escape_arg(node['explanation']))
+        if explanation and abbr not in self.handled_abbrs:
+            self.context.append(',%s}' % self.escape_arg(explanation))
             self.handled_abbrs.add(abbr)
         else:
             self.context.append('}')

sphinx/writers/text.py

@@ -1237,8 +1237,8 @@ class TextTranslator(SphinxTranslator):
         self.add_text('')
 
     def depart_abbreviation(self, node: Element) -> None:
-        if node.hasattr('explanation'):
-            self.add_text(' (%s)' % node['explanation'])
+        if explanation := node.get('explanation', ''):
+            self.add_text(f' ({explanation})')
 
     def visit_manpage(self, node: Element) -> None:
         return self.visit_literal_emphasis(node)

{sphinx-8.2.0rc1.dist-info → sphinx-8.2.0rc2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Sphinx
-Version: 8.2.0rc1
+Version: 8.2.0rc2
 Summary: Python documentation generator
 Author-email: Adam Turner <aa-turner@users.noreply.github.com>, Georg Brandl <georg@python.org>
 Requires-Python: >=3.11
@@ -80,6 +80,8 @@ Requires-Dist: types-requests==2.32.0.20241016 ; extra == "lint"
 Requires-Dist: types-urllib3==1.26.25.14 ; extra == "lint"
 Requires-Dist: pyright==1.1.394 ; extra == "lint"
 Requires-Dist: pytest>=8.0 ; extra == "lint"
+Requires-Dist: pypi-attestations==0.0.21 ; extra == "lint"
+Requires-Dist: betterproto==2.0.0b6 ; extra == "lint"
 Requires-Dist: pytest>=8.0 ; extra == "test"
 Requires-Dist: pytest-xdist[psutil]>=3.4 ; extra == "test"
 Requires-Dist: defusedxml>=0.7.1 ; extra == "test"

{sphinx-8.2.0rc1.dist-info → sphinx-8.2.0rc2.dist-info}/RECORD

@@ -1,7 +1,7 @@
-sphinx/__init__.py,sha256=dVckQZ6ig5QscpPmyYL2kdkRNqT5haCioIizMTwSh3A,1796
+sphinx/__init__.py,sha256=lfwYis272_lwAvX7LUgeOdj89vxhx5LYGdyOUd4cnPw,1796
 sphinx/__main__.py,sha256=PYSg7M8rY5VgULh3SJEaYMWsB1YFJw7f40b50yW8NEE,163
 sphinx/addnodes.py,sha256=QFvrCg9bGgH_zsGFVeUzGWcvqIQXtC-b7jXUYZEJRsk,18502
-sphinx/application.py,sha256=hu8uHn5oJf9c-OE3Dv8ivjaq1e-MbBFalY5yY1HB24U,66881
+sphinx/application.py,sha256=FgR54sWE9-hH548ZUbe3x0v_NlRRUAZ4JjorhwDF8eg,66893
 sphinx/config.py,sha256=7Raa_GVF6S0uZWDbYL6VkG9N8OlKHM7g5s5CPgyHNtU,34297
 sphinx/deprecation.py,sha256=U4BIydQiXjU3seaMOORp6bVeVleg-3xcAl_iU7bu2eA,2521
 sphinx/errors.py,sha256=lk9KPV3Grp64NwoU81JhK0rr1ybBS_d2iaXyhosVrSg,3413
@@ -60,7 +60,7 @@ sphinx/domains/changeset.py,sha256=1X6fd-jiMIXShGfTpcHJMSddhh2dfEQ2PuTR9BTJrHw,5
 sphinx/domains/citation.py,sha256=SJf91v0GSlSOIrlbzXyGIIzmnbQTzphyBnoidATcIfo,6019
 sphinx/domains/index.py,sha256=cil8Ona4hde42Pj0T94LJoap6nGiLl3SOgB-_pv6ats,4341
 sphinx/domains/javascript.py,sha256=3ppeTmxJ8UqNYw_vsycIML9O-PmUh11iO1AeyTMHPxU,20359
-sphinx/domains/math.py,sha256=o3LWsF1-8FknDD66doR26Bru-eg_kasA0etHO2D_cTE,5163
+sphinx/domains/math.py,sha256=hUIZZQj0_jxEvIjyTz-a0JXEeNbWYUETpksGQJJYxlI,5279
 sphinx/domains/rst.py,sha256=4f_9iD51aLTg7RmG4IX-zTUtd3jguFWVP19mxCWsnjo,11252
 sphinx/domains/c/__init__.py,sha256=cBT1gP79uP2bTU5BSnfBh9fIiShQgmQeITcqk_S7dNw,33319
 sphinx/domains/c/_ast.py,sha256=gR-xM8BBOSWqaKbWKHaD9QqXNnq9p6WvyHAnlazznlo,65877
@@ -73,8 +73,8 @@ sphinx/domains/cpp/_ids.py,sha256=jPJHiDJfOLjE4UbK-Q_HGAJ4BwdzF9Nl6btBKoVstzQ,18
 sphinx/domains/cpp/_parser.py,sha256=M-t-1Kq9hi3UOiz7uXbvvH5SASwlI-vylwNIQcoaD3E,89792
 sphinx/domains/cpp/_symbol.py,sha256=1tsROVq-jl581QK21-qB7pvRunjTQOTXHJwk677LUuo,50957
 sphinx/domains/python/__init__.py,sha256=4Aozi8Q91OvN9iVUjehu24p8hV7awVnSUHUfMEoAQiQ,38812
-sphinx/domains/python/_annotations.py,sha256=waAsCsmzvD-ClwJrQORKVWXg-7ZIVzA_xqBPYJXb2k0,24104
-sphinx/domains/python/_object.py,sha256=DTSUVp5y6Es_1NvCh_s__dpjao1busEWQpbz_oVQa7Q,18181
+sphinx/domains/python/_annotations.py,sha256=n3U3HCfCaBZLFckTGeXdQvkI1MypvvQkz-CJ6H8S880,24648
+sphinx/domains/python/_object.py,sha256=TnWnLL7jLs0-eW8-xHUTuXqHVjEub7DsyKMC_-37RBM,18323
 sphinx/domains/std/__init__.py,sha256=Tt5yVzybfNtHpocDE-SJgRFseYci7P3TApDoUBI0ppU,53450
 sphinx/environment/__init__.py,sha256=s7rsls8sbyYpRUYd3ZFeC1911UJNyGJOZ8USuACGI5c,42417
 sphinx/environment/adapters/__init__.py,sha256=VnDotW2UbxjWeVITmz7iTsVrzqQcvmLHr3euKqqKHwo,34
@@ -103,19 +103,20 @@ sphinx/ext/linkcode.py,sha256=GQfIOkJYeTzGZEF3w7svb1qqSE4h2zgBp_fJ_2Kev6o,3040
 sphinx/ext/mathjax.py,sha256=EjoCWBiw4vaKGw0uZnHZLjbSyDQrBL5CJuriF-OaICE,5814
 sphinx/ext/todo.py,sha256=wqLW3cy2Sd2u_1ztkajAEJdKkyL-bM65jXw8s6trSvc,8002
 sphinx/ext/viewcode.py,sha256=LFnSYN9C-Ity8956BWbWnT6DL-lH-ol2ZXv02NZy5bA,14926
-sphinx/ext/apidoc/__init__.py,sha256=ZQ-vDujiIGKoQAEUOQuxijGqIem24cvoE4Kqi02zyrg,632
+sphinx/ext/apidoc/__init__.py,sha256=rvtSje1ayQSBwbVYJwkSPZV_NrdZiqdfvgy_dYOfAhI,2227
 sphinx/ext/apidoc/__main__.py,sha256=-kCJWW_BL2zpvylBkK3U_XqVBNKEAETeghxR_UHsJvw,182
-sphinx/ext/apidoc/_cli.py,sha256=YZq_RlPFbST28_RQ2CpM8Lq1wg3n3AkydxNiK1SutZ0,10145
-sphinx/ext/apidoc/_generate.py,sha256=MIQenFdmXQawcDvuREoOFUAUTqEApdR4sBuTI3nogb8,11895
-sphinx/ext/apidoc/_shared.py,sha256=Mlsrdc1N25WZRU6mvDAwEXKzYkZyYPUwM1SIZ5Fooqk,1785
-sphinx/ext/autodoc/__init__.py,sha256=Mfbr3-smg8dgK2VmLU1bofkr-izvzVYw-Cne0h8Isx8,121543
+sphinx/ext/apidoc/_cli.py,sha256=MeApBSdy14-cXJiuEJeY1E366xFFfqSuvrYNOatcUHo,10182
+sphinx/ext/apidoc/_extension.py,sha256=OjrJFA9HwEJrK392IayeGa4tnS5olRD_5FO58vxlpdw,7505
+sphinx/ext/apidoc/_generate.py,sha256=EAhpB2PUwsjdPNV6UN8KCOXbgWwaeOdmV577amk29iU,11909
+sphinx/ext/apidoc/_shared.py,sha256=wer5szQBKbF1be0NBW_DW2ugMb9zWZ1MvQAQE-DYbqc,2908
+sphinx/ext/autodoc/__init__.py,sha256=mJxBAfeBIllFjahYOItA2Hzp1IuToICYqIG6Su0Yh3A,121552
 sphinx/ext/autodoc/directive.py,sha256=BJZK0TxBUd4TtFj9f9IKnCoWGT_dxYu6BTZUjih-hPw,6112
 sphinx/ext/autodoc/importer.py,sha256=qxvFRJA1MTMqci8jak3UlvA7de3LKp9q88pt1w-cjbI,18706
 sphinx/ext/autodoc/mock.py,sha256=OGw-6UYfZS1jVkT5gZF9X_-IzP56bmas7SyXD7rYhWY,6135
 sphinx/ext/autodoc/preserve_defaults.py,sha256=EiHd8PtR1Xhf6Mj_9jhEvPBsFOqCtMnecwAIyVIsyJA,7174
 sphinx/ext/autodoc/type_comment.py,sha256=kThxHwGawkpljf7bsT6tfchKuzyB4MOK7n6ShSmGX6I,5696
 sphinx/ext/autodoc/typehints.py,sha256=rt9RqDSiORINmvElr63kvKDt8jG3iaKOLDUmbOVbJ4w,8279
-sphinx/ext/autosummary/__init__.py,sha256=yUc1P67C-WB_g9dlk6uebcFgkTg0UK-uIdM91rXuoWs,34159
+sphinx/ext/autosummary/__init__.py,sha256=EQt5LTPfbd9UIV6foOo5wj829qOc6K5bSUpwP_rLVUs,34547
 sphinx/ext/autosummary/generate.py,sha256=qJB7ItpMiz43xqXn5xtbUKldx7vbcPx8g-ytnfCCQ2U,30215
 sphinx/ext/autosummary/templates/autosummary/base.rst,sha256=AfG9oeDMTKBsBf2lUKr-NolOeV7ImT_JrKG3KQkEGzE,106
 sphinx/ext/autosummary/templates/autosummary/class.rst,sha256=1uu4SSX9KRCeNlcr7FMRZ-DrPuW7E6tQ7QZC1asnAL0,553
@@ -589,14 +590,14 @@ sphinx/util/texescape.py,sha256=HhjOV6qNFSF9nIddTdYozxW36AW5aScipgv6VWw0zaw,5579
 sphinx/util/typing.py,sha256=Mxhya-bwMNfO4wS2wAS1pYSB_nRR10d_kA4kduPAd6Q,25978
 sphinx/writers/__init__.py,sha256=efGdnx4MWlPEDzXACf4Q18Oi3GTyY5Ob14I_j3XXtXc,31
 sphinx/writers/html.py,sha256=S-OilBJkNb7AYA6SDdYmZ7FlPnyz-wFNWtCWNjmur4E,1911
-sphinx/writers/html5.py,sha256=QQe-jrd9ZqUJIku6U_ZDIJh9VovVJ2Ifq9DK7DOKNXw,38595
-sphinx/writers/latex.py,sha256=BsxROor8iIyjvo7J-7fKx9eZmk2oPLmTMS6ynp6UPOA,95932
+sphinx/writers/html5.py,sha256=M6D7F2KxtwNmdzACx9xIBcUFU7DoXAqkpUbQjRhqpEg,38602
+sphinx/writers/latex.py,sha256=uvdNZfnn1z6I59OEG1BGGiB6lYtt4fwoyI5mfYH-5wo,95958
 sphinx/writers/manpage.py,sha256=rwur1uSNhRsPlb4U1tXwtV3gqz-W1RD-yIw29Qmjxo4,15559
-sphinx/writers/texinfo.py,sha256=NW5AUZPllNN_8RNcLJmUWgBz0x1C7VUhpw5R1b7-oBw,52765
-sphinx/writers/text.py,sha256=gFnTt10DrAmI4exdOk54Tf7jUoc2GETum1yM-Qiu9N8,43911
+sphinx/writers/texinfo.py,sha256=WOMdKuYov6lt9PH34gsO1UbdYE48W3GdU0sZ7tw73pE,52791
+sphinx/writers/text.py,sha256=8FSF2vj0NaJHCMmHK3Rz6H8-iSMBpkyVT2VOT5-mLXA,43916
 sphinx/writers/xml.py,sha256=qaxAMR7htHmo3tQgqi9_8DD_B0HJEvz9hZH1iJwZkdk,1730
-sphinx-8.2.0rc1.dist-info/entry_points.txt,sha256=KU_c9jqXj7yyZylSz11XRIXG3gAZApQa0d5DmcfyA7M,188
-sphinx-8.2.0rc1.dist-info/LICENSE.rst,sha256=ZMlpGbuvOhO6oPEOQYzB_Ih2jOG5wH9be_SfD7I9sQY,1476
-sphinx-8.2.0rc1.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-sphinx-8.2.0rc1.dist-info/METADATA,sha256=2CSRLODfFyhCS3V7yfKv4ZiHvikX8-7sQJpYOeHOSD8,6895
-sphinx-8.2.0rc1.dist-info/RECORD,,
+sphinx-8.2.0rc2.dist-info/entry_points.txt,sha256=KU_c9jqXj7yyZylSz11XRIXG3gAZApQa0d5DmcfyA7M,188
+sphinx-8.2.0rc2.dist-info/LICENSE.rst,sha256=ZMlpGbuvOhO6oPEOQYzB_Ih2jOG5wH9be_SfD7I9sQY,1476
+sphinx-8.2.0rc2.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+sphinx-8.2.0rc2.dist-info/METADATA,sha256=2alT-9iNt5jsESX3EW3ddAhXBLXGq9LCfZM59_TnN-k,7008
+sphinx-8.2.0rc2.dist-info/RECORD,,