Merge branch 'autodoc-auto' of https://github.com/chrisjsewell/sphinx into autodoc-auto

Author: chrisjsewell

.github/workflows/create-release.yml

@@ -73,6 +73,8 @@ jobs:
 
       - name: Inspect PEP 740 attestations
         run: |
+          # resolution fails without betterproto and protobuf-specs
+          uv pip install "pypi-attestations==0.0.12" "sigstore-protobuf-specs==0.3.2" "betterproto==2.0.0b6"
           python -m pypi_attestations inspect dist/*.publish.attestation
 
       - name: Prepare attestation bundles for uploading

AUTHORS.rst

@@ -28,6 +28,7 @@ Contributors
 * Antonio Valentino -- qthelp builder, docstring inheritance
 * Antti Kaihola -- doctest extension (skipif option)
 * Barry Warsaw -- setup command improvements
+* Bart Kamphorst -- warning improvements
 * Ben Egan -- Napoleon improvements & viewcode improvements
 * Benjamin Peterson -- unittests
 * Blaise Laflamme -- pyramid theme

CHANGES.rst

@@ -10,7 +10,7 @@ Incompatible changes
 --------------------
 
 * #13044: Remove the internal and undocumented ``has_equations`` data
-  from the :py:class:`!MathDomain`` domain.
+  from the :py:class:`!MathDomain` domain.
   The undocumented :py:meth:`!MathDomain.has_equations` method
   now unconditionally returns ``True``.
   These are replaced by the ``has_maths_elements`` key of the page context dict.
@@ -62,10 +62,8 @@ Features added
   :confval:`python_trailing_comma_in_multi_line_signatures` and
   :confval:`javascript_trailing_comma_in_multi_line_signatures`
   configuration options.
-* #13264: Rename the :rst:dir:`math` directive's ``nowrap``option
-  to :rst:dir:`no-wrap``,
-  and rename the :rst:dir:`autosummary` directive's ``nosignatures``option
-  to :rst:dir:`no-signatures``.
+* #13264: Rename the :rst:dir:`math` directive's ``nowrap`` option
+  to :rst:dir:`math:no-wrap`.
   Patch by Adam Turner.
 * #13269: Added the option to disable the use of type comments in
   via the new :confval:`autodoc_use_type_comments` option,
@@ -115,6 +113,8 @@ Features added
   to automate API documentation generation
   from Python modules.
   Patch by Chris Sewell and Adam Turner.
+* #13335: Use ``misc.highlighting_failure`` subtype for Pygments unknown lexers.
+  Patch by Bart Kamphorst.
 
 Bugs fixed
 ----------
@@ -155,6 +155,8 @@ Bugs fixed
 * #13302, #13319: Use the correct indentation for continuation lines
   in :rst:dir:`productionlist` directives.
   Patch by Adam Turner.
+* #13328: Fix parsing of PEP 695 functions with return annotations.
+  Patch by Bénédikt Tran. Initial work by Arash Badie-Modiri.
 
 Testing
 -------

doc/internals/contributing.rst

@@ -121,16 +121,7 @@ These are the basic steps needed to start developing on Sphinx.
 
    .. code-block:: shell
 
-      git commit -m '#42: Add useful new feature that does this.'
-
-   GitHub recognizes certain phrases that can be used to automatically
-   update the issue tracker. For example:
-
-   .. code-block:: shell
-
-      git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
-
-   would close issue #42.
+      git commit -m 'Add useful new feature that does this.'
 
 #. Push changes in the branch to your forked repository on GitHub:
 
@@ -140,6 +131,11 @@ These are the basic steps needed to start developing on Sphinx.
 
 #. Submit a pull request from your branch to the ``master`` branch.
 
+   GitHub recognizes certain phrases that can be used to automatically
+   update the issue tracker.
+   For example, including 'Closes #42' in the body of your pull request
+   will close issue #42 if the PR is merged.
+
 #. Wait for a core developer or contributor to review your changes.
 
 

pyproject.toml

@@ -24,6 +24,8 @@ classifiers = [
     "Intended Audience :: Developers",
     "Intended Audience :: Education",
     "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Other Audience",
     "Intended Audience :: Science/Research",
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: BSD License",
@@ -43,17 +45,24 @@ classifiers = [
     "Framework :: Sphinx :: Theme",
     "Topic :: Documentation",
     "Topic :: Documentation :: Sphinx",
+    "Topic :: Education",
     "Topic :: Internet :: WWW/HTTP :: Site Management",
+    "Topic :: Internet :: WWW/HTTP :: Site Management :: Link Checking",
     "Topic :: Printing",
     "Topic :: Software Development",
     "Topic :: Software Development :: Documentation",
+    "Topic :: Text Editors :: Documentation",
     "Topic :: Text Processing",
     "Topic :: Text Processing :: General",
     "Topic :: Text Processing :: Indexing",
     "Topic :: Text Processing :: Markup",
     "Topic :: Text Processing :: Markup :: HTML",
     "Topic :: Text Processing :: Markup :: LaTeX",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Text Processing :: Markup :: reStructuredText",
+    "Topic :: Text Processing :: Markup :: XML",
     "Topic :: Utilities",
+    "Typing :: Typed",
 ]
 dependencies = [
     "sphinxcontrib-applehelp>=1.0.7",
@@ -91,8 +100,8 @@ lint = [
     "types-Pygments==2.19.0.20250107",
     "types-requests==2.32.0.20241016",  # align with requests
     "types-urllib3==1.26.25.14",
-    "pyright==1.1.393",
-    "pytest>=6.0",
+    "pyright==1.1.394",
+    "pytest>=8.0",
 ]
 test = [
     "pytest>=8.0",
@@ -103,6 +112,10 @@ test = [
     "typing_extensions>=4.9",  # for typing_extensions.Unpack
 ]
 
+[[project.authors]]
+name = "Adam Turner"
+email = "[email protected]"
+
 [[project.authors]]
 name = "Georg Brandl"
 email = "[email protected]"
@@ -191,101 +204,57 @@ ignore_missing_imports = true
 module = [
     # tests/
     "tests.conftest",
-    "tests.test_abc",
     "tests.test_addnodes",
     "tests.test_application",
-    "tests.test_errors",
     "tests.test_events",
     "tests.test_highlighting",
     "tests.test_project",
-    "tests.test_roles",
     "tests.test_versioning",
     # tests/test_builders
     "tests.test_builders.test_build",
-    "tests.test_builders.test_build_changes",
-    "tests.test_builders.test_build_dirhtml",
     "tests.test_builders.test_build_html",
     "tests.test_builders.test_build_html_5_output",
     "tests.test_builders.test_build_html_assets",
-    "tests.test_builders.test_build_html_code",
-    "tests.test_builders.test_build_html_download",
-    "tests.test_builders.test_build_html_highlight",
-    "tests.test_builders.test_build_html_image",
     "tests.test_builders.test_build_html_maths",
     "tests.test_builders.test_build_html_numfig",
     "tests.test_builders.test_build_html_tocdepth",
     "tests.test_builders.test_build_html_toctree",
     "tests.test_builders.test_build_linkcheck",
-    "tests.test_builders.test_build_manpage",
-    "tests.test_builders.test_build_text",
     "tests.test_builders.test_build_warnings",
-    "tests.test_builders.test_incremental_reading",
     # tests/test_directives
     "tests.test_directives.test_directive_code",
-    "tests.test_directives.test_directive_object_description",
-    "tests.test_directives.test_directive_option",
     "tests.test_directives.test_directives_no_typesetting",
-    # tests/test_domains
-    "tests.test_domains.test_domain_py_canonical",
     # tests/test_environment
     "tests.test_environment.test_environment",
-    "tests.test_environment.test_environment_indexentries",
-    "tests.test_environment.test_environment_record_dependencies",
     # tests/test_extensions
-    "tests.test_extensions.test_ext_autodoc_autoattribute",
     "tests.test_extensions.test_ext_autodoc_autoclass",
-    "tests.test_extensions.test_ext_autodoc_autofunction",
-    "tests.test_extensions.test_ext_autodoc_automodule",
-    "tests.test_extensions.test_ext_autodoc_autoproperty",
-    "tests.test_extensions.test_ext_autodoc_configs",
-    "tests.test_extensions.test_ext_autodoc_preserve_defaults",
-    "tests.test_extensions.test_ext_autodoc_private_members",
-    "tests.test_extensions.test_ext_autosectionlabel",
     "tests.test_extensions.test_ext_autosummary_imports",
-    "tests.test_extensions.test_ext_coverage",
-    "tests.test_extensions.test_ext_duration",
-    "tests.test_extensions.test_ext_extlinks",
-    "tests.test_extensions.test_ext_graphviz",
-    "tests.test_extensions.test_ext_ifconfig",
     "tests.test_extensions.test_ext_imgconverter",
-    "tests.test_extensions.test_ext_imgmockconverter",
     "tests.test_extensions.test_ext_intersphinx_cache",
     "tests.test_extensions.test_ext_math",
     "tests.test_extensions.test_ext_napoleon",
     "tests.test_extensions.test_ext_todo",
     "tests.test_extensions.test_ext_viewcode",
-    "tests.test_extensions.test_extension",
     # tests/test_intl
     "tests.test_intl.test_catalogs",
     "tests.test_intl.test_locale",
     # tests/test_markup
     "tests.test_markup.test_markup",
-    "tests.test_markup.test_metadata",
     "tests.test_markup.test_parser",
-    "tests.test_markup.test_smartquotes",
-    # tests/test_pycode
-    "tests.test_pycode.test_pycode_parser",
     # tests/test_theming
-    "tests.test_theming.test_html_theme",
     "tests.test_theming.test_templating",
     "tests.test_theming.test_theming",
     # tests/test_transforms
     "tests.test_transforms.test_transforms_move_module_targets",
-    "tests.test_transforms.test_transforms_post_transforms_code",
     "tests.test_transforms.test_transforms_post_transforms_images",
     "tests.test_transforms.test_transforms_reorder_nodes",
     # tests/test_util
     "tests.test_util.test_util",
     "tests.test_util.test_util_display",
-    "tests.test_util.test_util_docstrings",
     "tests.test_util.test_util_docutils",
-    "tests.test_util.test_util_docutils_sphinx_directive",
     "tests.test_util.test_util_images",
-    "tests.test_util.test_util_importer",
     "tests.test_util.test_util_inventory",
-    "tests.test_util.test_util_lines",
     "tests.test_util.test_util_matching",
-    "tests.test_util.test_util_uri",
     # tests/test_writers
     "tests.test_writers.test_docutilsconf",
 ]
@@ -298,7 +267,6 @@ module = [
     "tests.test_search",
     # tests/test_builders
     "tests.test_builders.test_build_latex",
-    "tests.test_builders.test_build_texinfo",
     # tests/test_config
     "tests.test_config.test_config",
     # tests/test_directives
@@ -340,8 +308,6 @@ module = [
     "tests.test_util.test_util_inspect",
     "tests.test_util.test_util_logging",
     "tests.test_util.test_util_nodes",
-    "tests.test_util.test_util_rst",
-    "tests.test_util.test_util_template",
     "tests.test_util.test_util_typing",
 ]
 check_untyped_defs = false

sphinx/__init__.py

@@ -34,7 +34,7 @@
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 2, 0, 'beta', 0)
+version_info = (8, 2, 0, 'candidate', 2)
 
 package_dir = _StrPath(__file__).resolve().parent
 

sphinx/addnodes.py

@@ -436,7 +436,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
     *key* is categorization characters (usually a single character) for
     general index page. For the details of this, please see also:
-    :rst:dir:`glossary` and issue #2320.
+    :rst:dir:`glossary` and https://github.com/sphinx-doc/sphinx/pull/2320.
     """
 
 

sphinx/builders/__init__.py

@@ -47,6 +47,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence, Set
+    from gettext import NullTranslations
     from typing import Any, Literal
 
     from docutils.nodes import Node
@@ -135,17 +136,21 @@ def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
         self.parallel_ok = False
         self.finish_tasks: Any = None
 
+    @property
+    def _translator(self) -> NullTranslations | None:
+        return self.app.translator
+
     def get_translator_class(self, *args: Any) -> type[nodes.NodeVisitor]:
         """Return a class of translator."""
-        return self.app.registry.get_translator_class(self)
+        return self.env._registry.get_translator_class(self)
 
     def create_translator(self, *args: Any) -> nodes.NodeVisitor:
         """Return an instance of translator.
 
         This method returns an instance of ``default_translator_class`` by default.
         Users can replace the translator class with ``app.set_translator()`` API.
         """
-        return self.app.registry.create_translator(self, *args)
+        return self.env._registry.create_translator(self, *args)
 
     # helper methods
     def init(self) -> None:
@@ -626,7 +631,7 @@ def read_doc(self, docname: str, *, _cache: bool = True) -> None:
 
         filename = str(env.doc2path(docname))
         filetype = get_filetype(self.app.config.source_suffix, filename)
-        publisher = self.app.registry.get_publisher(self.app, filetype)
+        publisher = self.env._registry.get_publisher(self.app, filetype)
         self.env.current_document._parser = publisher.parser
         # record_dependencies is mutable even though it is in settings,
         # explicitly re-initialise for each document
@@ -661,7 +666,7 @@ def write_doctree(
         _cache: bool = True,
     ) -> None:
         """Write the doctree to a file, to be used as a cache by re-builds."""
-        # make it picklable
+        # make it pickleable
         doctree.reporter = None  # type: ignore[assignment]
         doctree.transformer = None  # type: ignore[assignment]