Merge branch 'master' into workflow-simplification

Author: AA-Turner

.gitattributes

@@ -65,4 +65,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

AUTHORS.rst

@@ -102,6 +102,7 @@ Contributors
 * Slawek Figiel -- additional warning suppression
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
+* Steve Piercy -- documentation improvements
 * \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder

CHANGES.rst

@@ -19,6 +19,12 @@ 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.
+* #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
 ----------

doc/extdev/markupapi.rst

@@ -173,9 +173,9 @@ The methods are used as follows:
       def run(self) -> list[Node]:
           container = docutils.nodes.Element()
           # either
-          nested_parse_with_titles(self.state, self.result, container)
+          nested_parse_with_titles(self.state, self.result, container, self.content_offset)
           # or
-          self.state.nested_parse(self.result, 0, container)
+          self.state.nested_parse(self.result, self.content_offset, container)
           parsed = container.children
           return parsed
 

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:`r'\\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).
 
@@ -1694,7 +1694,7 @@ Macros
   .. hint::
 
      If adding to preamble the loading of ``tocloft`` package, also add to
-     preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it
+     preamble :code-tex:`\\renewcommand\\sphinxtableofcontentshook{}` else it
      will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection`
      cancelling ``tocloft`` customization.
 

doc/man/sphinx-build.rst

@@ -272,13 +272,13 @@ Options
    From Sphinx 8.1, :option:`!--keep-going` is always enabled.
    Previously, it was only applicable whilst using :option:`--fail-on-warning`,
    which by default exited :program:`sphinx-build` on the first warning.
-   Using :option:`!--keep-going` runs :program:`!sphinx-build` to completion
+   Using :option:`!--keep-going` runs :program:`sphinx-build` to completion
    and exits with exit status 1 if errors are encountered.
 
    .. versionadded:: 1.8
    .. versionchanged:: 8.1
       :program:`sphinx-build` no longer exits on the first warning,
-      meaning that in effect :option:`!--fail-on-warning` is always enabled.
+      meaning that in effect :option:`!--keep-going` is always enabled.
       The option is retained for compatibility, but may be removed at some
       later date.
 

doc/usage/configuration.rst

@@ -3668,7 +3668,7 @@ and which failures and redirects it ignores.
    .. versionadded:: 4.1
 
    .. versionchanged:: 8.3
-      Setting :confval:`!linkcheck_allowed_redirects` to the empty directory
+      Setting :confval:`!linkcheck_allowed_redirects` to an empty dictionary
       may now be used to warn on all redirects encountered
       by the *linkcheck* builder.
 

pyproject.toml

@@ -92,19 +92,19 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.7",
+    "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.7",
+    "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,12 @@ 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_images",
     "tests.test_util.test_util_inventory",
     # tests/test_writers
     "tests.test_writers.test_docutilsconf",
@@ -340,7 +338,6 @@ module = [
     # 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/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/javascript.py

@@ -137,8 +137,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         return fullname, prefix
 

sphinx/domains/python/_annotations.py

@@ -552,15 +552,18 @@ def _keyword_only_separator() -> addnodes.desc_parameter:
 def _pseudo_parse_arglist(
     signode: desc_signature,
     arglist: str,
+    *,
     multi_line_parameter_list: bool = False,
     trailing_comma: bool = True,
+    env: BuildEnvironment,
 ) -> None:
     """'Parse' a list of arguments separated by commas.
 
     Arguments can have "optional" annotations given by enclosing them in
     brackets.  Currently, this will split at any comma, even if it's inside a
     string literal (e.g. default argument value).
     """
+    # TODO: decompose 'env' parameter into only the required bits
     paramlist = addnodes.desc_parameterlist()
     paramlist['multi_line_parameter_list'] = multi_line_parameter_list
     paramlist['multi_line_trailing_comma'] = trailing_comma
@@ -583,9 +586,30 @@ def _pseudo_parse_arglist(
                 ends_open += 1
                 argument = argument[:-1].strip()
             if argument:
-                stack[-1] += addnodes.desc_parameter(
-                    '', '', addnodes.desc_sig_name(argument, argument)
-                )
+                param_with_annotation, _, default_value = argument.partition('=')
+                param_name, _, annotation = param_with_annotation.partition(':')
+                del param_with_annotation
+
+                node = addnodes.desc_parameter()
+                node += addnodes.desc_sig_name('', param_name.strip())
+                if annotation:
+                    children = _parse_annotation(annotation.strip(), env=env)
+                    node += addnodes.desc_sig_punctuation('', ':')
+                    node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_name('', '', *children)  # type: ignore[arg-type]
+                if default_value:
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_operator('', '=')
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += nodes.inline(
+                        '',
+                        default_value.strip(),
+                        classes=['default_value'],
+                        support_smartquotes=False,
+                    )
+                stack[-1] += node
             while ends_open:
                 stack.append(addnodes.desc_optional())
                 stack[-2] += stack[-1]

sphinx/domains/python/_object.py

@@ -363,8 +363,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
             except (NotImplementedError, ValueError) as exc:
                 # duplicated parameter names raise ValueError and not a SyntaxError
@@ -374,8 +375,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         else:
             if self.needs_arglist():

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."""