Merge branch 'master' into autosummary-class

.github/workflows/main.yml

@@ -342,4 +342,4 @@ jobs:
       env:
         VIRTUALENV_SYSTEM_SITE_PACKAGES: "1"
     - name: codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5

.ruff.toml

@@ -222,7 +222,7 @@ select = [
     # ruff-specific rules ('RUF')
 #    "RUF001",  # String contains ambiguous {}. Did you mean {}?
     "RUF002",  # Docstring contains ambiguous {}. Did you mean {}?
-#    "RUF003",  # Comment contains ambiguous {}. Did you mean {}?
+    "RUF003",  # Comment contains ambiguous {}. Did you mean {}?
     "RUF005",  # Consider `{expression}` instead of concatenation
     "RUF006",  # Store a reference to the return value of `{expr}.{method}`
     "RUF007",  # Prefer `itertools.pairwise()` over `zip()` when iterating over successive pairs
@@ -231,7 +231,7 @@ select = [
     "RUF010",  # Use explicit conversion flag
 #    "RUF012",  # Mutable class attributes should be annotated with `typing.ClassVar`
     "RUF013",  # PEP 484 prohibits implicit `Optional`
-#    "RUF015",  # Prefer `next({iterable})` over single element slice
+    "RUF015",  # Prefer `next({iterable})` over single element slice
     "RUF016",  # Slice in indexed access to type `{value_type}` uses type `{index_type}` instead of an integer
     "RUF017",  # Avoid quadratic list summation
     "RUF018",  # Avoid assignment expressions in `assert` statements
@@ -243,13 +243,21 @@ select = [
     "RUF024",  # Do not pass mutable objects as values to `dict.fromkeys`
     "RUF026",  # `default_factory` is a positional-only argument to `defaultdict`
 #    "RUF027",  # Possible f-string without an `f` prefix
-#    "RUF028",  # This suppression comment is invalid because {}
-#    "RUF029",  # Function `{name}` is declared `async`, but doesn't `await` or use `async` features.
-    "RUF030",  # `print()` expression in `assert` statement is likely unintentional
-#    "RUF031",  # Use parentheses for tuples in subscripts.
+    "RUF028",  # This suppression comment is invalid because {}
+    "RUF029",  # Function `{name}` is declared `async`, but doesn't `await` or use `async` features.
+    "RUF030",  # `print()` call in `assert` statement is likely unintentional
+    "RUF031",  # Use parentheses for tuples in subscripts
     "RUF032",  # `Decimal()` called with float literal argument
     "RUF033",  # `__post_init__` method with argument defaults
-    "RUF034",  # Useless if-else condition
+    "RUF034",  # Useless `if`-`else` condition
+    "RUF035",  # Unsafe use of `{name}` detected
+    "RUF036",  # `None` not at the end of the type annotation.
+    "RUF038",  # `Literal[True, False, ...]` can be replaced with `Literal[...] | bool`
+#    "RUF039",  # First argument to {call} is not raw string
+    "RUF040",  # Non-string literal used as assert message
+    "RUF041",  # Unnecessary nested `Literal`
+#    "RUF048",  # `__version__` may contain non-integral-like elements
+    "RUF055",  # Plain string pattern passed to `re` function
 #    "RUF100",  # Unused `noqa` directive
     "RUF101",  # `{original}` is a redirect to `{target}`
     "RUF200",  # Failed to parse pyproject.toml: {message}
@@ -292,10 +300,10 @@ select = [
 [lint.per-file-ignores]
 "doc/*" = [
     "ANN",  # documentation doesn't need annotations
-    "TCH001",  # documentation doesn't need type-checking blocks
+    "TC001",  # documentation doesn't need type-checking blocks
 ]
 "doc/conf.py" = ["INP001", "W605"]
-"doc/development/tutorials/examples/*" = ["INP001"]
+"doc/development/tutorials/examples/*" = ["I002", "INP001"]
 # allow print() in the tutorial
 "doc/development/tutorials/examples/recipe.py" = [
     "FURB118",
@@ -359,8 +367,8 @@ select = [
 ]
 
 # these tests need old ``typing`` generic aliases
-"tests/test_util/test_util_typing.py" = ["UP006", "UP007", "UP035"]
-"tests/test_util/typing_test_data.py" = ["FA100", "PYI030", "UP006", "UP007", "UP035"]
+"tests/test_util/test_util_typing.py" = ["RUF036", "UP006", "UP007", "UP035"]
+"tests/test_util/typing_test_data.py" = ["FA100", "I002", "PYI030", "UP006", "UP007", "UP035"]
 
 "utils/*" = [
     "T201",  # whitelist ``print`` for stdout messages
@@ -377,6 +385,9 @@ inline-quotes = "single"
 forced-separate = [
     "tests",
 ]
+required-imports = [
+    "from __future__ import annotations",
+]
 
 [format]
 preview = true

CHANGES.rst

@@ -26,6 +26,12 @@ Bugs fixed
 
 * #13060: HTML Search: use ``Map`` to store per-file term scores.
   Patch by James Addison
+* #13130: LaTeX docs: ``pdflatex`` index creation may fail for index entries
+  in French.  See :confval:`latex_use_xindy`.
+  Patch by Jean-François B.
+* LaTeX: fix a ``7.4.0`` typo in a default for ``\sphinxboxsetup``
+  (refs: PR #13152).
+  Patch by Jean-François B.
 
 Testing
 -------

doc/man/sphinx-build.rst

@@ -141,7 +141,7 @@ Options
    .. versionchanged:: 6.2
       Add ``--jobs`` long option.
 
-.. option:: -c path, --config-dir path
+.. option:: -c path, --conf-dir path
 
    Don't look for the :file:`conf.py` in the source directory, but use the given
    configuration directory instead.  Note that various other files and paths
@@ -152,7 +152,7 @@ Options
    .. versionadded:: 0.3
 
    .. versionchanged:: 7.3
-      Add ``--config-dir`` long option.
+      Add ``--conf-dir`` long option.
 
 .. option:: -C, --isolated
 

doc/usage/configuration.rst

@@ -3157,6 +3157,9 @@ These options influence LaTeX output.
    * The default is :code-py:`False` for :code-py:`'pdflatex'`,
      but :code-py:`True` is recommended for non-English documents as soon
      as some indexed terms use non-ASCII characters from the language script.
+     Attempting to index a term whose first character is non-ASCII
+     will break the build, if :confval:`latex_use_xindy` is left to its
+     default :code-py:`False`.
 
    Sphinx adds some dedicated support to the :program:`xindy` base distribution
    for using :code-py:`'pdflatex'` engine with Cyrillic scripts.

pyproject.toml

@@ -82,12 +82,12 @@ docs = [
 ]
 lint = [
     "flake8>=6.0",
-    "ruff==0.7.3",
+    "ruff==0.8.1",
     "mypy==1.13.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
     "types-defusedxml==0.7.0.20240218",
-    "types-docutils==0.21.0.20241005",
+    "types-docutils==0.21.0.20241128",
     "types-Pillow==10.2.0.20240822",
     "types-Pygments==2.18.0.20240506",
     "types-requests==2.32.0.20241016",  # align with requests

sphinx/__init__.py

@@ -1,5 +1,7 @@
 """The Sphinx documentation toolchain."""
 
+from __future__ import annotations
+
 __version__ = '8.2.0'
 __display_version__ = __version__  # used for command line version
 

sphinx/__main__.py

@@ -1,5 +1,7 @@
 """The Sphinx documentation toolchain."""
 
+from __future__ import annotations
+
 import sys
 
 from sphinx.cmd.build import main

sphinx/_cli/util/colour.py

@@ -4,7 +4,7 @@
 
 import os
 import sys
-from collections.abc import Callable  # NoQA: TCH003
+from collections.abc import Callable  # NoQA: TC003
 
 if sys.platform == 'win32':
     import colorama

sphinx/application.py

@@ -26,7 +26,7 @@
 from sphinx.project import Project
 from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import docutils, logging
-from sphinx.util._pathlib import _StrPath
+from sphinx.util._pathlib import _StrPath, _StrPathProperty
 from sphinx.util.build_phase import BuildPhase
 from sphinx.util.console import bold
 from sphinx.util.display import progress_message
@@ -140,6 +140,11 @@ class Sphinx:
     warningiserror: Final = False
     _warncount: int
 
+    srcdir = _StrPathProperty()
+    confdir = _StrPathProperty()
+    outdir = _StrPathProperty()
+    doctreedir = _StrPathProperty()
+
     def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[str] | None,
                  outdir: str | os.PathLike[str], doctreedir: str | os.PathLike[str],
                  buildername: str, confoverrides: dict | None = None,

sphinx/builders/__init__.py

@@ -23,6 +23,7 @@
     rst,
 )
 from sphinx.util._importer import import_object
+from sphinx.util._pathlib import _StrPathProperty
 from sphinx.util.build_phase import BuildPhase
 from sphinx.util.console import bold
 from sphinx.util.display import progress_message, status_iterator
@@ -48,7 +49,6 @@
     from sphinx.application import Sphinx
     from sphinx.config import Config
     from sphinx.events import EventManager
-    from sphinx.util._pathlib import _StrPath
     from sphinx.util.tags import Tags
 
 
@@ -81,7 +81,7 @@ class Builder:
     # doctree versioning method
     versioning_method = 'none'
     versioning_compare = False
-    #: Whether it is safe to make parallel :meth:`~.Builder.write_doc()` calls.
+    #: Whether it is safe to make parallel :meth:`~.Builder.write_doc` calls.
     allow_parallel: bool = False
     # support translation
     use_message_catalog = True
@@ -94,11 +94,16 @@ class Builder:
     #: The file format produced by the builder allows images to be embedded using data-URIs.
     supported_data_uri_images: bool = False
 
+    srcdir = _StrPathProperty()
+    confdir = _StrPathProperty()
+    outdir = _StrPathProperty()
+    doctreedir = _StrPathProperty()
+
     def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
-        self.srcdir: _StrPath = app.srcdir
-        self.confdir: _StrPath = app.confdir
-        self.outdir: _StrPath = app.outdir
-        self.doctreedir: _StrPath = app.doctreedir
+        self.srcdir = app.srcdir
+        self.confdir = app.confdir
+        self.outdir = app.outdir
+        self.doctreedir = app.doctreedir
         ensuredir(self.doctreedir)
 
         self.app: Sphinx = app

sphinx/builders/changes.py

@@ -61,10 +61,7 @@ def write_documents(self, _docnames: Set[str]) -> None:
             return
         logger.info(bold(__('writing summary file...')))
         for changeset in changesets:
-            if isinstance(changeset.descname, tuple):
-                descname = changeset.descname[0]
-            else:
-                descname = changeset.descname
+            descname = changeset.descname
             ttext = self.typemap[changeset.type]
             context = changeset.content.replace('\n', ' ')
             if descname and changeset.docname.startswith('c-api'):

sphinx/builders/latex/nodes.py

@@ -1,5 +1,7 @@
 """Additional nodes for LaTeX writer."""
 
+from __future__ import annotations
+
 from docutils import nodes
 
 

sphinx/builders/latex/transforms.py

@@ -151,7 +151,7 @@ def renumber_footnotes(self) -> None:
                     break
 
             # assign new footnote number
-            old_label = cast(nodes.label, footnote[0])
+            old_label = cast('nodes.label', footnote[0])
             old_label.replace_self(nodes.label('', str(num)))
             if old_label in footnote['names']:
                 footnote['names'].remove(old_label.astext())
@@ -455,7 +455,7 @@ def visit_footnote_reference(self, node: nodes.footnote_reference) -> None:
         number = node.astext().strip()
         docname = node['docname']
         if (docname, number) in self.appeared:
-            footnote = self.appeared[(docname, number)]
+            footnote = self.appeared[docname, number]
             footnote['referred'] = True
 
             mark = footnotemark('', number, refid=node['refid'])
@@ -471,7 +471,7 @@ def visit_footnote_reference(self, node: nodes.footnote_reference) -> None:
                 node.replace_self(footnote)
                 footnote.walkabout(self)
 
-            self.appeared[(docname, number)] = footnote
+            self.appeared[docname, number] = footnote
         raise nodes.SkipNode
 
     def get_footnote_by_reference(

sphinx/builders/linkcheck.py

@@ -251,7 +251,7 @@ def _add_uri(self, uri: str, node: nodes.Element) -> None:
         :param uri: URI to add
         :param node: A node class where the URI was found
         """
-        builder = cast(CheckExternalLinksBuilder, self.app.builder)
+        builder = cast('CheckExternalLinksBuilder', self.app.builder)
         hyperlinks = builder.hyperlinks
         docname = self.env.docname
 

sphinx/directives/__init__.py

@@ -9,11 +9,11 @@
 from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
-from sphinx.addnodes import desc_signature  # NoQA: TCH001
+from sphinx.addnodes import desc_signature  # NoQA: TC001
 from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
-from sphinx.util.typing import ExtensionMetadata, OptionSpec  # NoQA: TCH001
+from sphinx.util.typing import ExtensionMetadata, OptionSpec  # NoQA: TC001
 
 if TYPE_CHECKING:
     from docutils.nodes import Node
@@ -81,7 +81,7 @@ def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
                     self._doc_field_type_map[name] = (field, False)
 
                 if field.is_typed:
-                    typed_field = cast(TypedField, field)
+                    typed_field = cast('TypedField', field)
                     for name in typed_field.typenames:
                         self._doc_field_type_map[name] = (field, True)
 
@@ -282,7 +282,11 @@ def run(self) -> list[Node]:
 
         if self.names:
             # needed for association of version{added,changed} directives
-            self.env.temp_data['object'] = self.names[0]
+            object_name: ObjDescT = self.names[0]
+            if isinstance(object_name, tuple):
+                self.env.temp_data['object'] = str(object_name[0])
+            else:
+                self.env.temp_data['object'] = str(object_name)
         self.before_content()
         content_children = self.parse_content_to_nodes(allow_section_headings=True)
         content_node = addnodes.desc_content('', *content_children)
@@ -292,7 +296,7 @@ def run(self) -> list[Node]:
             'object-description-transform', self.domain, self.objtype, content_node
         )
         DocFieldTransformer(self).transform_all(content_node)
-        self.env.temp_data['object'] = None
+        self.env.temp_data['object'] = ''
         self.after_content()
 
         if node['no-typesetting']:
@@ -342,7 +346,7 @@ def run(self) -> list[Node]:
             )
             messages += [error]
 
-        return cast(list[nodes.Node], messages)
+        return cast('list[nodes.Node]', messages)
 
 
 class DefaultDomain(SphinxDirective):

sphinx/directives/other.py

@@ -376,7 +376,7 @@ def run(self) -> list[Node]:
             # Use these depths to determine where the nested sections should
             # be placed in the doctree.
             n_sects_to_raise = current_depth - nested_depth + 1
-            parent = cast(nodes.Element, self.state.parent)
+            parent = cast('nodes.Element', self.state.parent)
             for _i in range(n_sects_to_raise):
                 if parent.parent:
                     parent = parent.parent

sphinx/directives/patches.py

@@ -38,15 +38,15 @@ def run(self) -> list[Node]:
             return result
 
         assert len(result) == 1
-        figure_node = cast(nodes.figure, result[0])
+        figure_node = cast('nodes.figure', result[0])
         if name:
             # set ``name`` to figure_node if given
             self.options['name'] = name
             self.add_name(figure_node)
 
         # copy lineno from image node
         if figure_node.line is None and len(figure_node) == 2:
-            caption = cast(nodes.caption, figure_node[1])
+            caption = cast('nodes.caption', figure_node[1])
             figure_node.line = caption.line
 
         return [figure_node]
@@ -163,7 +163,7 @@ def run(self) -> list[Node]:
         return ret
 
     def add_target(self, ret: list[Node]) -> None:
-        node = cast(nodes.math_block, ret[0])
+        node = cast('nodes.math_block', ret[0])
 
         # assign label automatically if math_number_all enabled
         if node['label'] == '' or (self.config.math_number_all and not node['label']):  # NoQA: PLC1901