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

sphinx/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = '8.2.0rc1'
+__version__ = '8.2.1'
 __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, 1, 'final', 0)
 
 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]