Merge branch 'master' into latex_fontawesome6

Author: jfbu

.gitattributes

@@ -62,4 +62,5 @@ tests/roots/test-pycode/cp_1251_coded.py working-tree-encoding=windows-1251
 
 tests/js/fixtures/**/*.js                           generated
 sphinx/search/minified-js/*.js                      generated
+sphinx/search/_stopwords/                           generated
 sphinx/themes/bizstyle/static/css3-mediaqueries.js  generated

CHANGES.rst

@@ -19,14 +19,22 @@ Features added
 * #13439: linkcheck: Permit warning on every redirect with
   ``linkcheck_allowed_redirects = {}``.
   Patch by Adam Turner.
+* #13497: Support C domain objects in the table of contents.
 * #13500: LaTeX: add support for ``fontawesome6`` package.
   Patch by Jean-François B.
+* #13535: html search: Update to the latest version of Snowball (v3.0.1).
+  Patch by Adam Turner.
+* #13704: autodoc: Detect :py:func:`typing_extensions.overload <typing.overload>`
+  and :py:func:`~typing.final` decorators.
+  Patch by Spencer Brown.
 
 Bugs fixed
 ----------
 
 * #13369: Correctly parse and cross-reference unpacked type annotations.
   Patch by Alicia Garcia-Raboso.
+* #13528: Add tilde ``~`` prefix support for :rst:role:`py:deco`.
+  Patch by Shengyu Zhang and Adam Turner.
 
 Testing
 -------

doc/extdev/event_callbacks.rst

@@ -70,8 +70,8 @@ Below is an overview of the core event that happens during a build.
       14. apply post-transforms (by priority): docutils.document -> docutils.document
       15. event.doctree-resolved(app, doctree, docname)
           - In the event that any reference nodes fail to resolve, the following may emit:
-          - event.missing-reference(env, node, contnode)
-          - event.warn-missing-reference(domain, node)
+          - event.missing-reference(app, env, node, contnode)
+          - event.warn-missing-reference(app, domain, node)
 
    16. Generate output files
    17. event.build-finished(app, exception)

doc/internals/contributing.rst

@@ -337,13 +337,15 @@ Updating generated files
 ------------------------
 
 * JavaScript stemming algorithms in :file:`sphinx/search/non-minified-js/*.js`
-  are generated using `snowball <https://github.com/snowballstem/snowball>`_
-  by cloning the repository, executing ``make dist_libstemmer_js`` and then
-  unpacking the tarball which is generated in :file:`dist` directory.
+  and stopword files in :file:`sphinx/search/_stopwords/`
+  are generated from the `Snowball project`_
+  by running :file:`utils/generate_snowball.py`.
 
   Minified files in :file:`sphinx/search/minified-js/*.js` are generated from
-  non-minified ones using :program:`uglifyjs` (installed via npm), with ``-m``
-  option to enable mangling.
+  non-minified ones using :program:`uglifyjs` (installed via npm).
+  See :file:`sphinx/search/minified-js/README.rst`.
+
+  .. _Snowball project: https://snowballstem.org/
 
 * The :file:`searchindex.js` files found in
   the :file:`tests/js/fixtures/*` directories

doc/latex.rst

@@ -500,7 +500,7 @@ Keys that don't need to be overridden unless in special cases are:
    .. hint::
 
       If the key value is set to
-      :code-tex:`'\\newcommand\\sphinxbackoftitlepage{<Extra
+      :code-tex:`r'\\newcommand\\sphinxbackoftitlepage{<Extra
       material>}\\sphinxmaketitle'`, then ``<Extra material>`` will be
       typeset on back of title page (``'manual'`` docclass only).
 

pyproject.toml

@@ -92,19 +92,19 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.9",
+    "ruff==0.11.10",
     "mypy==1.15.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
-    "types-defusedxml==0.7.0.20240218",
-    "types-docutils==0.21.0.20241128",
+    "types-defusedxml==0.7.0.20250516",
+    "types-docutils==0.21.0.20250514",
     "types-Pillow==10.2.0.20240822",
-    "types-Pygments==2.19.0.20250305",
-    "types-requests==2.32.0.20250328",  # align with requests
+    "types-Pygments==2.19.0.20250516",
+    "types-requests==2.32.0.20250515",  # align with requests
     "types-urllib3==1.26.25.14",
     "pyright==1.1.400",
     "pytest>=8.0",
-    "pypi-attestations==0.0.25",
+    "pypi-attestations==0.0.26",
     "betterproto==2.0.0b6",
 ]
 test = [
@@ -135,13 +135,13 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.9",
+    "ruff==0.11.10",
     "sphinx-lint>=0.9",
 ]
 package = [
     "betterproto==2.0.0b6",  # resolution fails without betterproto
     "build",
-    "pypi-attestations==0.0.25",
+    "pypi-attestations==0.0.26",
     "twine>=6.1",
 ]
 test = [
@@ -164,11 +164,11 @@ types = [
 type-stubs = [
     # align with versions used elsewhere
     "types-colorama==0.4.15.20240311",
-    "types-defusedxml==0.7.0.20240218",
-    "types-docutils==0.21.0.20241128",
+    "types-defusedxml==0.7.0.20250516",
+    "types-docutils==0.21.0.20250514",
     "types-Pillow==10.2.0.20240822",
-    "types-Pygments==2.19.0.20250305",
-    "types-requests==2.32.0.20250328",
+    "types-Pygments==2.19.0.20250516",
+    "types-requests==2.32.0.20250515",
     "types-urllib3==1.26.25.14",
 ]
 
@@ -283,14 +283,10 @@ module = [
     "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_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_docutils",
-    "tests.test_util.test_util_inventory",
     # tests/test_writers
     "tests.test_writers.test_docutilsconf",
 ]
@@ -333,13 +329,9 @@ module = [
     "tests.test_extensions.test_ext_napoleon_docstring",
     # tests/test_intl
     "tests.test_intl.test_intl",
-    # tests/test_pycode
-    "tests.test_pycode.test_pycode",
-    "tests.test_pycode.test_pycode_ast",
     # tests/test_transforms
     "tests.test_transforms.test_transforms_post_transforms",
     # tests/test_util
-    "tests.test_util.test_util_fileutil",
     "tests.test_util.test_util_i18n",
     "tests.test_util.test_util_inspect",
     "tests.test_util.test_util_logging",

sphinx/directives/other.py

@@ -5,7 +5,6 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
-import docutils
 from docutils import nodes
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.misc import Class
@@ -22,15 +21,14 @@
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import Any, ClassVar, Final
+    from typing import Any, ClassVar
 
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 
-DU_22_PLUS: Final = docutils.__version_info__ >= (0, 22, 0, 'alpha', 0)
 glob_re = re.compile(r'.*[*?\[].*')
 logger = logging.getLogger(__name__)
 
@@ -332,14 +330,6 @@ def run(self) -> list[Node]:
         surrounding_section_level = memo.section_level
         memo.title_styles = []
         memo.section_level = 0
-        if DU_22_PLUS:
-            # https://github.com/sphinx-doc/sphinx/issues/13539
-            # https://sourceforge.net/p/docutils/code/10093/
-            # https://sourceforge.net/p/docutils/patches/213/
-            surrounding_section_parents = memo.section_parents
-            memo.section_parents = []
-        else:
-            surrounding_section_parents = []
         try:
             self.state.nested_parse(
                 self.content, self.content_offset, node, match_titles=True
@@ -375,8 +365,6 @@ def run(self) -> list[Node]:
             return []
         finally:
             memo.title_styles = surrounding_title_styles
-            if DU_22_PLUS:
-                memo.section_parents = surrounding_section_parents
             memo.section_level = surrounding_section_level
 
 

sphinx/domains/c/__init__.py

@@ -39,7 +39,7 @@
 
     from docutils.nodes import Element, Node, TextElement, system_message
 
-    from sphinx.addnodes import pending_xref
+    from sphinx.addnodes import desc_signature, pending_xref
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
     from sphinx.domains.c._symbol import LookupKey
@@ -309,6 +309,32 @@ def after_content(self) -> None:
         self.env.current_document.c_parent_symbol = self.oldParentSymbol
         self.env.ref_context['c:parent_key'] = self.oldParentKey
 
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        last_symbol: Symbol = self.env.current_document.c_last_symbol
+        return tuple(map(str, last_symbol.get_full_nested_name().names))
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        if not sig_node.get('_toc_parts'):
+            return ''
+
+        config = self.config
+        objtype = sig_node.parent.get('objtype')
+        if config.add_function_parentheses and (
+            objtype in {'function', 'method'}
+            or (objtype == 'macro' and '(' in sig_node.rawsource)
+        ):
+            parens = '()'
+        else:
+            parens = ''
+        *parents, name = sig_node['_toc_parts']
+        if config.toc_object_entries_show_parents == 'domain':
+            return '::'.join((name + parens,))
+        if config.toc_object_entries_show_parents == 'hide':
+            return name + parens
+        if config.toc_object_entries_show_parents == 'all':
+            return '::'.join([*parents, name + parens])
+        return ''
+
 
 class CMemberObject(CObject):
     object_type = 'member'

sphinx/domains/python/__init__.py

@@ -29,7 +29,7 @@
     from collections.abc import Iterable, Iterator, Sequence, Set
     from typing import Any, ClassVar
 
-    from docutils.nodes import Element, Node, TextElement
+    from docutils.nodes import Element, Node
 
     from sphinx.addnodes import desc_signature, pending_xref
     from sphinx.application import Sphinx
@@ -594,23 +594,17 @@ def process_link(
 
 
 class _PyDecoXRefRole(PyXRefRole):
-    def __init__(
+    def process_link(
         self,
-        fix_parens: bool = False,
-        lowercase: bool = False,
-        nodeclass: type[Element] | None = None,
-        innernodeclass: type[TextElement] | None = None,
-        warn_dangling: bool = False,
-    ) -> None:
-        super().__init__(
-            fix_parens=True,
-            lowercase=lowercase,
-            nodeclass=nodeclass,
-            innernodeclass=innernodeclass,
-            warn_dangling=warn_dangling,
+        env: BuildEnvironment,
+        refnode: Element,
+        has_explicit_title: bool,
+        title: str,
+        target: str,
+    ) -> tuple[str, str]:
+        title, target = super().process_link(
+            env, refnode, has_explicit_title, title, target
         )
-
-    def update_title_and_target(self, title: str, target: str) -> tuple[str, str]:
         return f'@{title}', target
 
 

sphinx/pycode/parser.py

@@ -247,9 +247,9 @@ def __init__(self, buffers: list[str], encoding: str) -> None:
         self.deforders: dict[str, int] = {}
         self.finals: list[str] = []
         self.overloads: dict[str, list[Signature]] = {}
-        self.typing: str | None = None
-        self.typing_final: str | None = None
-        self.typing_overload: str | None = None
+        self.typing_mods: set[str] = set()
+        self.typing_final_names: set[str] = set()
+        self.typing_overload_names: set[str] = set()
         super().__init__()
 
     def get_qualname_for(self, name: str) -> list[str] | None:
@@ -295,11 +295,8 @@ def add_variable_annotation(self, name: str, annotation: ast.AST) -> None:
             self.annotations[basename, name] = ast_unparse(annotation)
 
     def is_final(self, decorators: list[ast.expr]) -> bool:
-        final = []
-        if self.typing:
-            final.append('%s.final' % self.typing)
-        if self.typing_final:
-            final.append(self.typing_final)
+        final = {f'{modname}.final' for modname in self.typing_mods}
+        final |= self.typing_final_names
 
         for decorator in decorators:
             try:
@@ -311,11 +308,8 @@ def is_final(self, decorators: list[ast.expr]) -> bool:
         return False
 
     def is_overload(self, decorators: list[ast.expr]) -> bool:
-        overload = []
-        if self.typing:
-            overload.append('%s.overload' % self.typing)
-        if self.typing_overload:
-            overload.append(self.typing_overload)
+        overload = {f'{modname}.overload' for modname in self.typing_mods}
+        overload |= self.typing_overload_names
 
         for decorator in decorators:
             try:
@@ -348,22 +342,24 @@ def visit_Import(self, node: ast.Import) -> None:
         for name in node.names:
             self.add_entry(name.asname or name.name)
 
-            if name.name == 'typing':
-                self.typing = name.asname or name.name
-            elif name.name == 'typing.final':
-                self.typing_final = name.asname or name.name
-            elif name.name == 'typing.overload':
-                self.typing_overload = name.asname or name.name
+            if name.name in {'typing', 'typing_extensions'}:
+                self.typing_mods.add(name.asname or name.name)
+            elif name.name in {'typing.final', 'typing_extensions.final'}:
+                self.typing_final_names.add(name.asname or name.name)
+            elif name.name in {'typing.overload', 'typing_extensions.overload'}:
+                self.typing_overload_names.add(name.asname or name.name)
 
     def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
         """Handles Import node and record the order of definitions."""
         for name in node.names:
             self.add_entry(name.asname or name.name)
 
-            if node.module == 'typing' and name.name == 'final':
-                self.typing_final = name.asname or name.name
-            elif node.module == 'typing' and name.name == 'overload':
-                self.typing_overload = name.asname or name.name
+            if node.module not in {'typing', 'typing_extensions'}:
+                continue
+            if name.name == 'final':
+                self.typing_final_names.add(name.asname or name.name)
+            elif name.name == 'overload':
+                self.typing_overload_names.add(name.asname or name.name)
 
     def visit_Assign(self, node: ast.Assign) -> None:
         """Handles Assign node and pick up a variable comment."""