Sphinx 8.2.0rc1__tar.gz → 8.2.0rc2__tar.gz

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/CHANGES.rst

@@ -111,6 +111,12 @@ Features added
   Patch by Adam Turner.
 * #13335: Use ``misc.highlighting_failure`` subtype for Pygments unknown lexers.
   Patch by Bart Kamphorst.
+* #13354: Insert abbreviation nodes (hover text) for positional- and keyword-only
+  separators in Python signatures.
+  Patch by Adam Turner.
+* #13333: Add the :mod:`sphinx.ext.autodoc` extension,
+  to automate API documentation generation from Python modules.
+  Patch by Chris Sewell and Adam Turner.
 
 Bugs fixed
 ----------

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/PKG-INFO

@@ -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.0rc2/doc/usage/extensions/apidoc.rst

@@ -0,0 +1,172 @@
+.. _ext-apidoc:
+
+:mod:`sphinx.ext.apidoc` -- Generate API documentation from Python packages
+===========================================================================
+
+.. py:module:: sphinx.ext.apidoc
+   :synopsis: Generate API documentation from Python modules
+
+.. index:: pair: automatic; documentation
+.. index:: pair: generation; documentation
+.. index:: pair: generate; documentation
+
+.. versionadded:: 8.2
+
+.. role:: code-py(code)
+   :language: Python
+
+:mod:`sphinx.ext.apidoc` is a tool for automatic generation
+of Sphinx sources from Python packages.
+It provides the :program:`sphinx-apidoc` command-line tool as an extension,
+allowing it to be run during the Sphinx build process.
+
+The extension writes generated source files to a provided directory,
+which are then read by Sphinx using the :mod:`sphinx.ext.autodoc` extension.
+
+.. warning::
+
+   :mod:`sphinx.ext.apidoc` generates source files that
+   use :mod:`sphinx.ext.autodoc` to document all found modules.
+   If any modules have side effects on import,
+   these will be executed by ``autodoc`` when :program:`sphinx-build` is run.
+
+   If you document scripts (as opposed to library modules),
+   make sure their main routine is protected by
+   an ``if __name__ == '__main__'`` condition.
+
+
+Configuration
+-------------
+
+The apidoc extension uses the following configuration values:
+
+.. confval:: apidoc_modules
+   :type: :code-py:`Sequence[dict[str, str | int | bool | Sequence[str] | Set[str]]`
+   :default: :code-py:`()`
+
+   A list or sequence of dictionaries describing modules to document.
+   If a value is left unspecified in any dictionary,
+   the general configuration value is used as the default.
+
+   For example:
+
+   .. code-block:: python
+
+      apidoc_modules = [
+          {'path': 'path/to/module', 'destination': 'source/'},
+          {
+              'path': 'path/to/another_module',
+              'destination': 'source/',
+              'exclude_patterns': ['**/test*'],
+              'max_depth': 4,
+              'follow_links': False,
+              'separate_modules': False,
+              'include_private': False,
+              'no_headings': False,
+              'module_first': False,
+              'implicit_namespaces': False,
+              'automodule_options': {
+                  'members', 'show-inheritance', 'undoc-members'
+              },
+          },
+      ]
+
+
+   Valid keys are:
+
+   :code-py:`'path'`
+     The path to the module to document (**required**).
+     This must be absolute or relative to the configuration directory.
+
+   :code-py:`'destination'`
+     The output directory for generated files (**required**).
+     This must be relative to the source directory,
+     and will be created if it does not exist.
+
+   :code-py:`'exclude_patterns'`
+     See :confval:`apidoc_exclude_patterns`.
+
+   :code-py:`'max_depth'`
+     See :confval:`apidoc_max_depth`.
+
+   :code-py:`'follow_links'`
+     See :confval:`apidoc_follow_links`.
+
+   :code-py:`'separate_modules'`
+     See :confval:`apidoc_separate_modules`.
+
+   :code-py:`'include_private'`
+     See :confval:`apidoc_include_private`.
+
+   :code-py:`'no_headings'`
+     See :confval:`apidoc_no_headings`.
+
+   :code-py:`'module_first'`
+     See :confval:`apidoc_module_first`.
+
+   :code-py:`'implicit_namespaces'`
+     See :confval:`apidoc_implicit_namespaces`.
+
+   :code-py:`'automodule_options'`
+     See :confval:`apidoc_automodule_options`.
+
+.. confval:: apidoc_exclude_patterns
+   :type: :code-py:`Sequence[str]`
+   :default: :code-py:`()`
+
+   A sequence of patterns to exclude from generation.
+   These may be literal paths or :py:mod:`fnmatch`-style patterns.
+
+.. confval:: apidoc_max_depth
+   :type: :code-py:`int`
+   :default: :code-py:`4`
+
+   The maximum depth of submodules to show in the generated table of contents.
+
+.. confval:: apidoc_follow_links
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   Follow symbolic links.
+
+.. confval:: apidoc_separate_modules
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   Put documentation for each module on an individual page.
+
+.. confval:: apidoc_include_private
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   Generate documentation for '_private' modules with leading underscores.
+
+.. confval:: apidoc_no_headings
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   Do not create headings for the modules/packages.
+   Useful when source docstrings already contain headings.
+
+.. confval:: apidoc_module_first
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   Place module documentation before submodule documentation.
+
+.. confval:: apidoc_implicit_namespaces
+   :type: :code-py:`bool`
+   :default: :code-py:`False`
+
+   By default sphinx-apidoc processes sys.path searching for modules only.
+   Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
+   structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+   (notice that ``bar`` and ``foo`` are namespaces, not modules).
+
+   Interpret module paths using :pep:`420` implicit namespaces.
+
+.. confval:: apidoc_automodule_options
+   :type: :code-py:`Set[str]`
+   :default: :code-py:`{'members', 'show-inheritance', 'undoc-members'}`
+
+   Options to pass to generated :rst:dir:`automodule` directives.

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/doc/usage/extensions/index.rst

@@ -21,6 +21,7 @@ These extensions are built in and can be activated by respective entries in the
 .. toctree::
    :maxdepth: 1
 
+   apidoc
    autodoc
    autosectionlabel
    autosummary

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/pyproject.toml

@@ -102,6 +102,8 @@ lint = [
     "types-urllib3==1.26.25.14",
     "pyright==1.1.394",
     "pytest>=8.0",
+    "pypi-attestations==0.0.21",
+    "betterproto==2.0.0b6",
 ]
 test = [
     "pytest>=8.0",
@@ -191,11 +193,7 @@ strict_optional = false
 [[tool.mypy.overrides]]
 module = [
     "imagesize",
-    "pypi_attestations",
     "pyximport",
-    "sigstore.models",
-    "sigstore.verify",
-    "sigstore.verify.policy",
     "snowballstemmer",
 ]
 ignore_missing_imports = true

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/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-8.2.0rc1 → sphinx-8.2.0rc2}/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-8.2.0rc1 → sphinx-8.2.0rc2}/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-8.2.0rc1 → sphinx-8.2.0rc2}/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-8.2.0rc1 → sphinx-8.2.0rc2}/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-8.2.0rc2/sphinx/ext/apidoc/__init__.py

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

{sphinx-8.2.0rc1 → sphinx-8.2.0rc2}/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)