Merge branch 'dependabot/pip/types-docutils-0.21.0.20250516' of github.com:sphinx-doc/sphinx into dependabot/pip/types-docutils-0.21.0.20250516

Author: adamtheturtle

CHANGES.rst

@@ -22,12 +22,17 @@ Features added
 * #13497: Support C domain objects in the table of contents.
 * #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)

pyproject.toml

@@ -97,7 +97,7 @@ lint = [
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
     "types-defusedxml==0.7.0.20250516",
-    "types-docutils==0.21.0.20250516",
+    "types-docutils==0.21.0.20250523",
     "types-Pillow==10.2.0.20240822",
     "types-Pygments==2.19.0.20250516",
     "types-requests==2.32.0.20250515",  # align with requests
@@ -165,7 +165,7 @@ type-stubs = [
     # align with versions used elsewhere
     "types-colorama==0.4.15.20240311",
     "types-defusedxml==0.7.0.20250516",
-    "types-docutils==0.21.0.20250516",
+    "types-docutils==0.21.0.20250523",
     "types-Pillow==10.2.0.20240822",
     "types-Pygments==2.19.0.20250516",
     "types-requests==2.32.0.20250515",
@@ -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/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."""

sphinx/themes/basic/static/language_data.js.jinja

@@ -1,12 +1,13 @@
 /*
  * This script contains the language-specific data used by searchtools.js,
- * namely the list of stopwords, stemmer, scorer and splitter.
+ * namely the set of stopwords, stemmer, scorer and splitter.
  */
 
-var stopwords = {{ search_language_stop_words }};
+const stopwords = new Set({{ search_language_stop_words }});
+window.stopwords = stopwords;  // Export to global scope
 
 {% if search_language_stemming_code %}
-/* Non-minified version is copied as a separate JS file, if available */
+/* Non-minified versions are copied as separate JavaScript files, if available */
 {{ search_language_stemming_code|safe }}
 {% endif -%}
 

sphinx/themes/basic/static/searchtools.js

@@ -287,11 +287,8 @@ const Search = {
       const queryTermLower = queryTerm.toLowerCase();
 
       // maybe skip this "word"
-      // stopwords array is from language_data.js
-      if (
-        stopwords.indexOf(queryTermLower) !== -1 ||
-        queryTerm.match(/^\d+$/)
-      )
+      // stopwords set is from language_data.js
+      if (stopwords.has(queryTermLower) || queryTerm.match(/^\d+$/))
         return;
 
       // stem the word

sphinx/util/parsing.py

@@ -5,19 +5,15 @@
 import contextlib
 from typing import TYPE_CHECKING
 
-import docutils
 from docutils.nodes import Element
 from docutils.statemachine import StringList, string2lines
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
-    from typing import Final
 
     from docutils.nodes import Node
     from docutils.parsers.rst.states import RSTState
 
-DU_22_PLUS: Final = docutils.__version_info__ >= (0, 22, 0, 'alpha', 0)
-
 
 def nested_parse_to_nodes(
     state: RSTState,
@@ -79,23 +75,15 @@ def _fresh_title_style_context(state: RSTState) -> Iterator[None]:
     memo = state.memo
     surrounding_title_styles: list[str | tuple[str, str]] = memo.title_styles
     surrounding_section_level: int = memo.section_level
-    if DU_22_PLUS:
-        surrounding_section_parents = memo.section_parents
-    else:
-        surrounding_section_parents = []
     # clear current title styles
     memo.title_styles = []
     memo.section_level = 0
-    if DU_22_PLUS:
-        memo.section_parents = []
     try:
         yield
     finally:
         # reset title styles
         memo.title_styles = surrounding_title_styles
         memo.section_level = surrounding_section_level
-        if DU_22_PLUS:
-            memo.section_parents = surrounding_section_parents
 
 
 def _text_to_string_list(

tests/js/language_data.js

@@ -3,10 +3,11 @@
  * namely the list of stopwords, stemmer, scorer and splitter.
  */
 
-var stopwords = [];
+const stopwords = new Set([]);
+window.stopwords = stopwords;  // Export to global scope
 
 
-/* Non-minified version is copied as a separate JS file, if available */
+/* Non-minified versions are copied as separate JavaScript files, if available */
 
 /**
  * Dummy stemmer for languages without stemming rules.

tests/roots/test-ext-autodoc/target/final.py

@@ -3,6 +3,9 @@
 import typing
 from typing import final
 
+import typing_extensions
+from typing_extensions import final as final_ext  # noqa: UP035
+
 
 @typing.final
 class Class:
@@ -14,3 +17,11 @@ def meth1(self):
 
     def meth2(self):
         """docstring"""
+
+    @final_ext
+    def meth3(self):
+        """docstring"""
+
+    @typing_extensions.final
+    def meth4(self):
+        """docstring"""

tests/roots/test-ext-autodoc/target/overload3.py

@@ -0,0 +1,18 @@
+import typing
+from typing import TYPE_CHECKING, overload
+
+import typing_extensions
+from typing_extensions import overload as over_ext  # noqa: UP035
+
+
+@overload
+def test(x: int) -> int: ...
+@typing.overload
+def test(x: list[int]) -> list[int]: ...
+@over_ext
+def test(x: str) -> str: ...
+@typing_extensions.overload
+def test(x: float) -> float: ...
+def test(x):
+    """Documentation."""
+    return x

tests/test_domains/test_domain_py.py

@@ -1791,3 +1791,18 @@ def test_pep_695_and_pep_696_whitespaces_in_default(app, tp_list, tptext):
     text = f'.. py:function:: f{tp_list}() -> Annotated[T, Qux[int]()]'
     doctree = restructuredtext.parse(app, text)
     assert doctree.astext() == f'\n\nf{tptext}() -> Annotated[T, Qux[int]()]\n\n'
+
+
+def test_deco_role(app):
+    text = """\
+.. py:decorator:: foo.bar
+   :no-contents-entry:
+   :no-index-entry:
+   :no-typesetting:
+"""
+
+    doctree = restructuredtext.parse(app, text + '\n:py:deco:`foo.bar`')
+    assert doctree.astext() == '\n\n\n\n@foo.bar'
+
+    doctree = restructuredtext.parse(app, text + '\n:py:deco:`~foo.bar`')
+    assert doctree.astext() == '\n\n\n\n@bar'