From 4080be1e82a4942b64360ec3fe8c86438b494ef0 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 3 Oct 2024 16:58:37 +0200
Subject: [PATCH 01/29] Improve cross-reference documentation (#12944)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
---
 doc/usage/domains/index.rst           |  19 +--
 doc/usage/domains/python.rst          |  51 ++++++--
 doc/usage/referencing.rst             | 180 ++++++++++++++++----------
 doc/usage/restructuredtext/basics.rst |   2 +
 4 files changed, 165 insertions(+), 87 deletions(-)

diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst
index 8c47134159f..eda2da3f652 100644
--- a/doc/usage/domains/index.rst
+++ b/doc/usage/domains/index.rst
@@ -158,19 +158,22 @@ giving the domain name, i.e. ::
 Cross-referencing syntax
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-For cross-reference roles provided by domains, the same facilities exist as for
-general cross-references.  See :ref:`xref-syntax`.
-
+For cross-reference roles provided by domains,
+the same :ref:`cross-referencing modifiers <xref-modifiers>` exist
+as for general cross-references.
 In short:
 
-* You may supply an explicit title and reference target: ``:role:`title
-  <target>``` will refer to *target*, but the link text will be *title*.
+* You may supply an explicit title and reference target:
+  ``:py:mod:`mathematical functions <math>``` will refer to the ``math`` module,
+  but the link text will be "mathematical functions".
 
-* If you prefix the content with ``!``, no reference/hyperlink will be created.
+* If you prefix the content with an exclamation mark (``!``),
+  no reference/hyperlink will be created.
 
 * If you prefix the content with ``~``, the link text will only be the last
-  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+  component of the target.
+  For example, ``:py:meth:`~queue.Queue.get``` will
+  refer to ``queue.Queue.get`` but only display ``get`` as the link text.
 
 Built-in domains
 ----------------
diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst
index 5b98baa78b0..2ff27c4bb3d 100644
--- a/doc/usage/domains/python.rst
+++ b/doc/usage/domains/python.rst
@@ -716,18 +716,45 @@ a matching identifier is found:
 
    .. versionadded:: 0.4
 
-The name enclosed in this markup can include a module name and/or a class name.
-For example, ``:py:func:`filter``` could refer to a function named ``filter``
-in the current module, or the built-in function of that name.  In contrast,
-``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
-``foo`` module.
-
-Normally, names in these roles are searched first without any further
-qualification, then with the current module name prepended, then with the
-current module and class name (if any) prepended.  If you prefix the name with
-a dot, this order is reversed.  For example, in the documentation of Python's
-:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
-function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
+
+Target specification
+^^^^^^^^^^^^^^^^^^^^
+
+The target can be specified as a fully qualified name
+(e.g. ``:py:meth:`my_module.MyClass.my_method```)
+or any shortened version
+(e.g. ``:py:meth:`MyClass.my_method``` or ``:py:meth:`my_method```).
+See `target resolution`_ for details on the resolution of shortened names.
+
+:ref:`Cross-referencing modifiers <xref-modifiers>` can be applied.
+In short:
+
+* You may supply an explicit title and reference target:
+  ``:py:mod:`mathematical functions <math>``` will refer to the ``math`` module,
+  but the link text will be "mathematical functions".
+
+* If you prefix the content with an exclamation mark (``!``),
+  no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.
+  For example, ``:py:meth:`~queue.Queue.get``` will
+  refer to ``queue.Queue.get`` but only display ``get`` as the link text.
+
+
+Target resolution
+^^^^^^^^^^^^^^^^^
+
+A given link target name is resolved to an object using the following strategy:
+
+Names in these roles are searched first without any further qualification,
+then with the current module name prepended,
+then with the current module and class name (if any) prepended.
+
+If you prefix the name with a dot (``.``), this order is reversed.
+For example, in the documentation of Python's :py:mod:`codecs` module,
+``:py:func:`open``` always refers to the built-in function,
+while ``:py:func:`.open``` refers to :func:`codecs.open`.
 
 A similar heuristic is used to determine whether the name is an attribute of
 the currently documented class.
diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst
index 57611660f10..02beaa6b80a 100644
--- a/doc/usage/referencing.rst
+++ b/doc/usage/referencing.rst
@@ -4,83 +4,84 @@
 Cross-referencing syntax
 ========================
 
-Cross-references are generated by many semantic interpreted text roles.
-Basically, you only need to write ``:role:`target```, and a link will be
-created to the item named *target* of the type indicated by *role*.  The link's
-text will be the same as *target*.
-
-There are some additional facilities, however, that make cross-referencing
-roles more versatile:
-
-* You may supply an explicit title and reference target,
-  like in reStructuredText direct hyperlinks:
-  ``:role:`title <target>``` will refer to *target*,
-  but the link text will be *title*.
-
-* If you prefix the content with ``!``, no reference/hyperlink will be created.
-
-* If you prefix the content with ``~``, the link text will only be the last
-  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.  This
-  does not work with all cross-reference roles, but is domain specific.
-
-  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
-  tool-tip on mouse-hover) will always be the full target name.
-
-
-.. _any-role:
-
-Cross-referencing anything
---------------------------
-
-.. rst:role:: any
-
-   .. versionadded:: 1.3
-
-   This convenience role tries to do its best to find a valid target for its
-   reference text.
-
-   * First, it tries standard cross-reference targets that would be referenced
-     by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
-
-     Custom objects added to the standard domain by extensions (see
-     :meth:`.Sphinx.add_object_type`) are also searched.
-
-   * Then, it looks for objects (targets) in all loaded domains.  It is up to
-     the domains how specific a match must be.  For example, in the Python
-     domain a reference of ``:any:`Builder``` would match the
-     ``sphinx.builders.Builder`` class.
-
-   If none or multiple targets are found, a warning will be emitted.  In the
-   case of multiple targets, you can change "any" to a specific role.
-
-   This role is a good candidate for setting :confval:`default_role`.  If you
-   do, you can write cross-references without a lot of markup overhead.  For
-   example, in this Python function documentation::
-
-      .. function:: install()
-
-         This function installs a `handler` for every signal known by the
-         `signal` module.  See the section `about-signals` for more information.
-
-   there could be references to a glossary term (usually ``:term:`handler```), a
-   Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a
-   section (usually ``:ref:`about-signals```).
-
-   The :rst:role:`any` role also works together with the
-   :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
-   found, all object types of intersphinx inventories are also searched.
+One of Sphinx's most useful features is creating automatic cross-references
+through semantic cross-referencing roles.
+A cross reference to an object description, such as ``:func:`spam```,
+will create a link to the place where ``spam()`` is documented,
+appropriate to each output format (HTML, PDF, ePUB, etc.).
+
+Sphinx supports various cross-referencing roles to create links
+to other elements in the documentation.
+In general, writing ``:role:`target``` creates a link to
+the object called *target* of the type indicated by *role*.
+The link's text depends the role but is often the same as or similar to *target*.
+
+.. _xref-modifiers:
+
+The behavior can be modified in the following ways:
+
+* **Custom link text:**
+  You can specify the link text explicitly using the same
+  notation as in reStructuredText :ref:`external links <rst-external-links>`:
+  ``:role:`custom text <target>``` will refer to *target*
+  and display *custom text* as the text of the link.
+
+* **Suppressed link:**
+  Prefixing with an exclamation mark (``!``) prevents the creation of a link
+  but otherwise keeps the visual output of the role.
+
+  For example, writing ``:py:func:`!target``` displays :py:func:`!target`,
+  with no link generated.
+
+  This is helpful for cases in which the link target does not exist;
+  e.g. changelog entries that describe removed functionality,
+  or third-party libraries that don't support :doc:`intersphinx
+  </usage/extensions/intersphinx>`.
+  Suppressing the link prevents warnings in :confval:`nitpicky` mode.
+
+* **Modified domain reference:**
+  When :ref:`referencing domain objects <ref-objects>`,
+  a tilde ``~`` prefix shortens the link text the last component of the target.
+  For example, ``:py:meth:`~queue.Queue.get``` will
+  refer to ``queue.Queue.get`` but only display ``get`` as the link text.
+
+  In HTML output, the link's ``title`` attribute
+  (that is e.g. shown as a tool-tip on mouse-hover)
+  will always be the full target name.
+
+Some of the built-in cross-reference roles are:
+
+* :rst:role:`:any: <any>`,
+  :rst:role:`:doc: <doc>`,
+  :rst:role:`:ref: <ref>`
+* :rst:role:`:confval: <confval>`,
+  :rst:role:`:envvar: <envvar>`,
+  :rst:role:`:option: <option>`
+* :rst:role:`:manpage: <manpage>`,
+  :rst:role:`:pep: <pep>`,
+  :rst:role:`:rfc: <rfc>`
+* :rst:role:`download`,
+  :rst:role:`:index: <index>`
+  :rst:role:`:numref: <numref>`,
+  :rst:role:`:keyword: <keyword>`,
+  :rst:role:`:term: <term>`,
+  :rst:role:`:token: <token>`
+* :rst:role:`!:func:`
+  (this uses the :confval:`primary_domain`, e.g. :rst:role:`:py:func: <py:func>`)
+* :ref:`Domain cross-reference roles <ref-objects>`
+
+.. _ref-objects:
 
 Cross-referencing objects
 -------------------------
 
 These roles are described with their respective domains:
 
-* :ref:`Python <python-xref-roles>`
 * :ref:`C <c-xref-roles>`
 * :ref:`C++ <cpp-xref-roles>`
 * :ref:`JavaScript <js-xref-roles>`
 * :ref:`reStructuredText <rst-xref-roles>`
+* :ref:`Python <python-xref-roles>`
 
 
 .. _ref-role:
@@ -267,3 +268,48 @@ The following role creates a cross-reference to a term in a
 
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
+
+
+.. _any-role:
+
+Cross-referencing anything
+--------------------------
+
+.. rst:role:: any
+
+   .. versionadded:: 1.3
+
+   This convenience role tries to do its best to find a valid target for its
+   reference text.
+
+   * First, it tries standard cross-reference targets that would be referenced
+     by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
+
+     Custom objects added to the standard domain by extensions (see
+     :meth:`.Sphinx.add_object_type`) are also searched.
+
+   * Then, it looks for objects (targets) in all loaded domains.  It is up to
+     the domains how specific a match must be.  For example, in the Python
+     domain a reference of ``:any:`Builder``` would match the
+     ``sphinx.builders.Builder`` class.
+
+   If none or multiple targets are found, a warning will be emitted.  In the
+   case of multiple targets, you can change "any" to a specific role.
+
+   This role is a good candidate for setting :confval:`default_role`.  If you
+   do, you can write cross-references without a lot of markup overhead.  For
+   example, in this Python function documentation::
+
+      .. function:: install()
+
+         This function installs a `handler` for every signal known by the
+         `signal` module.  See the section `about-signals` for more information.
+
+   there could be references to a glossary term (usually ``:term:`handler```), a
+   Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a
+   section (usually ``:ref:`about-signals```).
+
+   The :rst:role:`any` role also works together with the
+   :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
+   found, all object types of intersphinx inventories are also searched.
+
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 53547486ac8..5d60ea81de4 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -203,6 +203,8 @@ Two more syntaxes are supported: *CSV tables* and *List tables*. They use an
 Hyperlinks
 ----------
 
+.. _rst-external-links:
+
 External links
 ~~~~~~~~~~~~~~
 

From a11698d4811838ea23d0da5963c0b7ddecddae2a Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Thu, 3 Oct 2024 17:31:53 +0100
Subject: [PATCH 02/29] Replace ``BuildEnvironment._update_config()`` with
 ``_config_status()`` (#12946)

---
 sphinx/environment/__init__.py | 59 ++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 25 deletions(-)

diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py
index 6ae9435c5b1..31e5508d09e 100644
--- a/sphinx/environment/__init__.py
+++ b/sphinx/environment/__init__.py
@@ -262,37 +262,46 @@ def setup(self, app: Sphinx) -> None:
         # setup domains (must do after all initialization)
         self.domains._setup()
 
-        # initialize config
-        self._update_config(app.config)
+        # Initialise config.
+        # The old config is self.config, restored from the pickled environment.
+        # The new config is app.config, always recreated from ``conf.py``
+        self.config_status, self.config_status_extra = self._config_status(
+            old_config=self.config, new_config=app.config
+        )
+        self.config = app.config
 
         # initialize settings
         self._update_settings(app.config)
 
-    def _update_config(self, config: Config) -> None:
-        """Update configurations by new one."""
-        self.config_status = CONFIG_OK
-        self.config_status_extra = ''
-        if self.config is None:
-            self.config_status = CONFIG_NEW
-        elif self.config.extensions != config.extensions:
-            self.config_status = CONFIG_EXTENSIONS_CHANGED
-            extensions = sorted(
-                set(self.config.extensions) ^ set(config.extensions))
+    @staticmethod
+    def _config_status(*, old_config: Config | None, new_config: Config) -> tuple[int, str]:
+        """Report the differences between two Config objects.
+
+        Returns a triple of:
+
+        1. The new configuration
+        2. A status code indicating how the configuration has changed.
+        3. A status message indicating what has changed.
+        """
+        if old_config is None:
+            return CONFIG_NEW, ''
+
+        if old_config.extensions != new_config.extensions:
+            old_extensions = set(old_config.extensions)
+            new_extensions = set(new_config.extensions)
+            extensions = old_extensions ^ new_extensions
             if len(extensions) == 1:
-                extension = extensions[0]
+                extension = extensions.pop()
             else:
-                extension = '%d' % (len(extensions),)
-            self.config_status_extra = f' ({extension!r})'
-        else:
-            # check if a config value was changed that affects how
-            # doctrees are read
-            for item in config.filter(frozenset({'env'})):
-                if self.config[item.name] != item.value:
-                    self.config_status = CONFIG_CHANGED
-                    self.config_status_extra = f' ({item.name!r})'
-                    break
-
-        self.config = config
+                extension = f'{len(extensions)}'
+            return CONFIG_EXTENSIONS_CHANGED, f' ({extension!r})'
+
+        # check if a config value was changed that affects how doctrees are read
+        for item in new_config.filter(frozenset({'env'})):
+            if old_config[item.name] != item.value:
+                return CONFIG_CHANGED, f' ({item.name!r})'
+
+        return CONFIG_OK, ''
 
     def _update_settings(self, config: Config) -> None:
         """Update settings by new config."""

From e5df455087e3b4869b6aafff03121ee2cecef249 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Thu, 3 Oct 2024 17:40:38 +0100
Subject: [PATCH 03/29] Move ``stable_hash()`` to a new private module
 (sphinx.util._serialise) (#12947)

---
 sphinx/builders/html/_build_info.py | 25 +++----------------------
 sphinx/util/_serialise.py           | 27 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 22 deletions(-)
 create mode 100644 sphinx/util/_serialise.py

diff --git a/sphinx/builders/html/_build_info.py b/sphinx/builders/html/_build_info.py
index 5b364c0d9fc..281ad5ab977 100644
--- a/sphinx/builders/html/_build_info.py
+++ b/sphinx/builders/html/_build_info.py
@@ -2,16 +2,14 @@
 
 from __future__ import annotations
 
-import hashlib
-import types
 from typing import TYPE_CHECKING
 
 from sphinx.locale import __
+from sphinx.util._serialise import stable_hash
 
 if TYPE_CHECKING:
     from collections.abc import Set
     from pathlib import Path
-    from typing import Any
 
     from sphinx.config import Config, _ConfigRebuild
     from sphinx.util.tags import Tags
@@ -57,10 +55,10 @@ def __init__(
 
         if config:
             values = {c.name: c.value for c in config.filter(config_categories)}
-            self.config_hash = _stable_hash(values)
+            self.config_hash = stable_hash(values)
 
         if tags:
-            self.tags_hash = _stable_hash(sorted(tags))
+            self.tags_hash = stable_hash(sorted(tags))
 
     def __eq__(self, other: BuildInfo) -> bool:  # type: ignore[override]
         return (self.config_hash == other.config_hash and
@@ -75,20 +73,3 @@ def dump(self, filename: Path, /) -> None:
             f'tags: {self.tags_hash}\n'
         )
         filename.write_text(build_info, encoding="utf-8")
-
-
-def _stable_hash(obj: Any) -> str:
-    """Return a stable hash for a Python data structure.
-
-    We can't just use the md5 of str(obj) as the order of collections
-    may be random.
-    """
-    if isinstance(obj, dict):
-        obj = sorted(map(_stable_hash, obj.items()))
-    if isinstance(obj, list | tuple | set | frozenset):
-        obj = sorted(map(_stable_hash, obj))
-    elif isinstance(obj, type | types.FunctionType):
-        # The default repr() of functions includes the ID, which is not ideal.
-        # We use the fully qualified name instead.
-        obj = f'{obj.__module__}.{obj.__qualname__}'
-    return hashlib.md5(str(obj).encode(), usedforsecurity=False).hexdigest()
diff --git a/sphinx/util/_serialise.py b/sphinx/util/_serialise.py
new file mode 100644
index 00000000000..e6627a8e6b0
--- /dev/null
+++ b/sphinx/util/_serialise.py
@@ -0,0 +1,27 @@
+"""Serialise objects to a stable representation."""
+
+from __future__ import annotations
+
+import hashlib
+import types
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+def stable_hash(obj: Any) -> str:
+    """Return a stable hash for a Python data structure.
+
+    We can't just use the md5 of str(obj) as the order of collections
+    may be random.
+    """
+    if isinstance(obj, dict):
+        obj = sorted(map(stable_hash, obj.items()))
+    if isinstance(obj, list | tuple | set | frozenset):
+        obj = sorted(map(stable_hash, obj))
+    elif isinstance(obj, type | types.FunctionType):
+        # The default repr() of functions includes the ID, which is not ideal.
+        # We use the fully qualified name instead.
+        obj = f'{obj.__module__}.{obj.__qualname__}'
+    return hashlib.md5(str(obj).encode(), usedforsecurity=False).hexdigest()

From b6f818f6001523998345db2c07f72ff5a8760265 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Thu, 3 Oct 2024 17:54:54 +0100
Subject: [PATCH 04/29] Add ``stable_str()`` (#12948)

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>
---
 sphinx/util/_serialise.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/sphinx/util/_serialise.py b/sphinx/util/_serialise.py
index e6627a8e6b0..11d95ee1f09 100644
--- a/sphinx/util/_serialise.py
+++ b/sphinx/util/_serialise.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+import json
 import types
 from typing import TYPE_CHECKING
 
@@ -25,3 +26,28 @@ def stable_hash(obj: Any) -> str:
         # We use the fully qualified name instead.
         obj = f'{obj.__module__}.{obj.__qualname__}'
     return hashlib.md5(str(obj).encode(), usedforsecurity=False).hexdigest()
+
+
+def stable_str(obj: Any, *, indent: int | None = None) -> str:
+    """Return a stable string representation of a Python data structure.
+
+    We can't just use ``str(obj)`` as the order of collections may be random.
+    """
+    return json.dumps(_stable_str_prep(obj), indent=indent)
+
+
+def _stable_str_prep(obj: Any) -> dict[str, Any] | list[Any] | str:
+    if isinstance(obj, dict):
+        # Convert to a sorted dict
+        obj = [(_stable_str_prep(k), _stable_str_prep(v)) for k, v in obj.items()]
+        obj.sort()
+        return dict(obj)
+    if isinstance(obj, list | tuple | set | frozenset):
+        # Convert to a sorted list
+        return sorted(map(_stable_str_prep, obj))
+    if isinstance(obj, type | types.FunctionType):
+        # The default repr() of functions includes the ID, which is not ideal.
+        # We use the fully qualified name instead.
+        return f'{obj.__module__}.{obj.__qualname__}'
+    # We can't do any better, just use the string representation
+    return str(obj)

From 75465458764a7d8d6dc80a0cfcf2d6a0af18e71b Mon Sep 17 00:00:00 2001
From: danieleades <33452915+danieleades@users.noreply.github.com>
Date: Thu, 3 Oct 2024 20:17:40 +0100
Subject: [PATCH 05/29] Further improve typing in `tests/` (#12816)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
---
 pyproject.toml                                |  3 --
 tests/test_events.py                          |  9 +++--
 .../test_ext_autodoc_autofunction.py          |  4 ++-
 tests/test_extensions/test_ext_napoleon.py    |  5 ++-
 tests/test_quickstart.py                      | 33 +++++++++++--------
 tests/test_search.py                          | 28 +++++++++-------
 tests/test_util/test_util_fileutil.py         |  4 +--
 7 files changed, 49 insertions(+), 37 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 9e00b59c2ac..aa650803a97 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -146,7 +146,6 @@ files = [
 exclude = [
     "tests/roots",
     # tests/
-    "^tests/test_events\\.py$",
     "^tests/test_quickstart\\.py$",
     "^tests/test_search\\.py$",
     # tests/test_builders
@@ -175,14 +174,12 @@ exclude = [
     # tests/test_extensions
     "^tests/test_extensions/test_ext_apidoc\\.py$",
     "^tests/test_extensions/test_ext_autodoc\\.py$",
-    "^tests/test_extensions/test_ext_autodoc_autofunction\\.py$",
     "^tests/test_extensions/test_ext_autodoc_events\\.py$",
     "^tests/test_extensions/test_ext_autodoc_mock\\.py$",
     "^tests/test_extensions/test_ext_autosummary\\.py$",
     "^tests/test_extensions/test_ext_doctest\\.py$",
     "^tests/test_extensions/test_ext_inheritance_diagram\\.py$",
     "^tests/test_extensions/test_ext_intersphinx\\.py$",
-    "^tests/test_extensions/test_ext_napoleon\\.py$",
     "^tests/test_extensions/test_ext_napoleon_docstring\\.py$",
     # tests/test_intl
     "^tests/test_intl/test_intl\\.py$",
diff --git a/tests/test_events.py b/tests/test_events.py
index 685646f4d96..df175787a17 100644
--- a/tests/test_events.py
+++ b/tests/test_events.py
@@ -8,7 +8,8 @@
 
 def test_event_priority():
     result = []
-    events = EventManager(object())  # pass an dummy object as an app
+    app = object()  # pass a dummy object as an app
+    events = EventManager(app)  # type: ignore[arg-type]
     events.connect('builder-inited', lambda app: result.append(1), priority=500)
     events.connect('builder-inited', lambda app: result.append(2), priority=500)
     # earlier
@@ -30,7 +31,8 @@ def test_event_allowed_exceptions():
     def raise_error(app):
         raise RuntimeError
 
-    events = EventManager(FakeApp())  # pass an dummy object as an app
+    app = FakeApp()  # pass a dummy object as an app
+    events = EventManager(app)  # type: ignore[arg-type]
     events.connect('builder-inited', raise_error, priority=500)
 
     # all errors are converted to ExtensionError
@@ -46,7 +48,8 @@ def test_event_pdb():
     def raise_error(app):
         raise RuntimeError
 
-    events = EventManager(FakeApp(pdb=True))  # pass an dummy object as an app
+    app = FakeApp(pdb=True)  # pass a dummy object as an app
+    events = EventManager(app)  # type: ignore[arg-type]
     events.connect('builder-inited', raise_error, priority=500)
 
     # errors aren't converted
diff --git a/tests/test_extensions/test_ext_autodoc_autofunction.py b/tests/test_extensions/test_ext_autodoc_autofunction.py
index 5dfa42d5a04..e70069bfd61 100644
--- a/tests/test_extensions/test_ext_autodoc_autofunction.py
+++ b/tests/test_extensions/test_ext_autodoc_autofunction.py
@@ -4,6 +4,8 @@
 source file translated by test_build.
 """
 
+from typing import Any
+
 import pytest
 
 from tests.test_extensions.autodoc_util import do_autodoc
@@ -109,7 +111,7 @@ def test_decorated(app):
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_singledispatch(app):
-    options = {}
+    options: dict[str, Any] = {}
     actual = do_autodoc(app, 'function', 'target.singledispatch.func', options)
     assert list(actual) == [
         '',
diff --git a/tests/test_extensions/test_ext_napoleon.py b/tests/test_extensions/test_ext_napoleon.py
index 9fd9c2d126a..59477dfe064 100644
--- a/tests/test_extensions/test_ext_napoleon.py
+++ b/tests/test_extensions/test_ext_napoleon.py
@@ -2,7 +2,6 @@
 
 import functools
 from collections import namedtuple
-from typing import Any
 from unittest import mock
 
 import pytest
@@ -111,7 +110,7 @@ def test_modify_in_place(self):
 
 class TestSetup:
     def test_unknown_app_type(self):
-        setup(object())
+        setup(object())  # type: ignore[arg-type]
 
     def test_add_config_values(self):
         app = mock.Mock(Sphinx)
@@ -146,7 +145,7 @@ def assert_skip(
         self,
         what: str,
         member: str,
-        obj: Any,
+        obj: object,
         expect_default_skip: bool,
         config_name: str,
     ) -> None:
diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py
index 7634637b3a7..0507d0c8243 100644
--- a/tests/test_quickstart.py
+++ b/tests/test_quickstart.py
@@ -1,8 +1,11 @@
 """Test the sphinx.quickstart module."""
 
 import time
+from collections.abc import Callable
 from io import StringIO
 from os import path
+from pathlib import Path
+from typing import Any
 
 import pytest
 
@@ -17,10 +20,12 @@ def setup_module():
     nocolor()
 
 
-def mock_input(answers, needanswer=False):
+def mock_input(
+    answers: dict[str, str], needanswer: bool = False
+) -> Callable[[str], str]:
     called = set()
 
-    def input_(prompt):
+    def input_(prompt: str) -> str:
         if prompt in called:
             raise AssertionError(
                 'answer for %r missing and no default present' % prompt
@@ -36,7 +41,7 @@ def input_(prompt):
     return input_
 
 
-real_input = input
+real_input: Callable[[str], str] = input
 
 
 def teardown_module():
@@ -95,13 +100,13 @@ def test_quickstart_defaults(tmp_path):
         'Project version': '0.1',
     }
     qs.term_input = mock_input(answers)
-    d = {}
+    d: dict[str, Any] = {}
     qs.ask_user(d)
     qs.generate(d)
 
     conffile = tmp_path / 'conf.py'
     assert conffile.is_file()
-    ns = {}
+    ns: dict[str, Any] = {}
     exec(conffile.read_text(encoding='utf8'), ns)  # NoQA: S102
     assert ns['extensions'] == []
     assert ns['templates_path'] == ['_templates']
@@ -145,13 +150,13 @@ def test_quickstart_all_answers(tmp_path):
         'Do you want to use the epub builder': 'yes',
     }
     qs.term_input = mock_input(answers, needanswer=True)
-    d = {}
+    d: dict[str, Any] = {}
     qs.ask_user(d)
     qs.generate(d)
 
     conffile = tmp_path / 'source' / 'conf.py'
     assert conffile.is_file()
-    ns = {}
+    ns: dict[str, Any] = {}
     exec(conffile.read_text(encoding='utf8'), ns)  # NoQA: S102
     assert ns['extensions'] == [
         'sphinx.ext.autodoc',
@@ -184,11 +189,11 @@ def test_generated_files_eol(tmp_path):
         'Project version': '0.1',
     }
     qs.term_input = mock_input(answers)
-    d = {}
+    d: dict[str, Any] = {}
     qs.ask_user(d)
     qs.generate(d)
 
-    def assert_eol(filename, eol):
+    def assert_eol(filename: Path, eol: str) -> None:
         content = filename.read_bytes().decode()
         assert all(l[-len(eol) :] == eol for l in content.splitlines(keepends=True))
 
@@ -204,7 +209,7 @@ def test_quickstart_and_build(tmp_path):
         'Project version': '0.1',
     }
     qs.term_input = mock_input(answers)
-    d = {}
+    d: dict[str, Any] = {}
     qs.ask_user(d)
     qs.generate(d)
 
@@ -223,13 +228,13 @@ def test_default_filename(tmp_path):
         'Project version': '0.1',
     }
     qs.term_input = mock_input(answers)
-    d = {}
+    d: dict[str, Any] = {}
     qs.ask_user(d)
     qs.generate(d)
 
     conffile = tmp_path / 'conf.py'
     assert conffile.is_file()
-    ns = {}
+    ns: dict[str, Any] = {}
     exec(conffile.read_text(encoding='utf8'), ns)  # NoQA: S102
 
 
@@ -247,7 +252,7 @@ def test_extensions(tmp_path):
 
     conffile = tmp_path / 'conf.py'
     assert conffile.is_file()
-    ns = {}
+    ns: dict[str, Any] = {}
     exec(conffile.read_text(encoding='utf8'), ns)  # NoQA: S102
     assert ns['extensions'] == ['foo', 'bar', 'baz']
 
@@ -263,6 +268,6 @@ def mock_isfile(path):
     qs.term_input = mock_input({
         'Please enter a new root path (or just Enter to exit)': '',
     })
-    d = {}
+    d: dict[str, Any] = {}
     with pytest.raises(SystemExit):
         qs.ask_user(d)
diff --git a/tests/test_search.py b/tests/test_search.py
index f350d192ac1..31918587a69 100644
--- a/tests/test_search.py
+++ b/tests/test_search.py
@@ -17,6 +17,10 @@
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
+    from pathlib import Path
+    from typing import Any
+
+    from sphinx.domains import ObjType
 
 JAVASCRIPT_TEST_ROOTS = [
     directory
@@ -52,9 +56,9 @@ class DummyDomain:
     def __init__(self, name: str, data: dict) -> None:
         self.name = name
         self.data = data
-        self.object_types = {}
+        self.object_types: dict[str, ObjType] = {}
 
-    def get_objects(self):
+    def get_objects(self) -> list[tuple[str, str, str, str, str, int]]:
         return self.data
 
 
@@ -72,7 +76,7 @@ def setup_module():
     parser = rst.Parser()
 
 
-def load_searchindex(path):
+def load_searchindex(path: Path) -> Any:
     searchindex = path.read_text(encoding='utf8')
     assert searchindex.startswith('Search.setIndex(')
     assert searchindex.endswith(')')
@@ -80,7 +84,7 @@ def load_searchindex(path):
     return json.loads(searchindex[16:-1])
 
 
-def is_registered_term(index, keyword):
+def is_registered_term(index: Any, keyword: str) -> bool:
     return index['terms'].get(keyword, []) != []
 
 
@@ -191,12 +195,12 @@ def test_IndexBuilder():
         ],
     )
     env = DummyEnvironment('1.0', DummyDomainsContainer(dummy1=domain1, dummy2=domain2))
-    doc = utils.new_document(b'test data', settings)
+    doc = utils.new_document('test data', settings)
     doc['file'] = 'dummy'
     parser.parse(FILE_CONTENTS, doc)
 
     # feed
-    index = IndexBuilder(env, 'en', {}, None)
+    index = IndexBuilder(env, 'en', {}, '')
     index.feed('docname1_1', 'filename1_1', 'title1_1', doc)
     index.feed('docname1_2', 'filename1_2', 'title1_2', doc)
     index.feed('docname2_2', 'filename2_2', 'title2_2', doc)
@@ -285,7 +289,7 @@ def test_IndexBuilder():
     index.dump(stream, 'pickle')
     stream.seek(0)
 
-    index2 = IndexBuilder(env, 'en', {}, None)
+    index2 = IndexBuilder(env, 'en', {}, '')
     index2.load(stream, 'pickle')
 
     assert index2._titles == index._titles
@@ -366,11 +370,11 @@ def test_IndexBuilder_lookup():
     env = DummyEnvironment('1.0', {})
 
     # zh
-    index = IndexBuilder(env, 'zh', {}, None)
+    index = IndexBuilder(env, 'zh', {}, '')
     assert index.lang.lang == 'zh'
 
     # zh_CN
-    index = IndexBuilder(env, 'zh_CN', {}, None)
+    index = IndexBuilder(env, 'zh_CN', {}, '')
     assert index.lang.lang == 'zh'
 
 
@@ -426,7 +430,7 @@ def test_search_index_is_deterministic(app):
     assert_is_sorted(index, '')
 
 
-def is_title_tuple_type(item: list[int | str]):
+def is_title_tuple_type(item: list[int | str]) -> bool:
     """
     In the search index, titles inside .alltitles are stored as a tuple of
     (document_idx, title_anchor). Tuples are represented as lists in JSON,
@@ -436,7 +440,9 @@ def is_title_tuple_type(item: list[int | str]):
     return len(item) == 2 and isinstance(item[0], int) and isinstance(item[1], str)
 
 
-def assert_is_sorted(item, path: str):
+def assert_is_sorted(
+    item: dict[str, str] | list[int | str] | int | str, path: str
+) -> None:
     lists_not_to_sort = {
         # Each element of .titles is related to the element of .docnames in the same position.
         # The ordering is deterministic because .docnames is sorted.
diff --git a/tests/test_util/test_util_fileutil.py b/tests/test_util/test_util_fileutil.py
index 33633a8b020..7ffa83fc223 100644
--- a/tests/test_util/test_util_fileutil.py
+++ b/tests/test_util/test_util_fileutil.py
@@ -6,12 +6,12 @@
 import pytest
 
 from sphinx.jinja2glue import BuiltinTemplateLoader
-from sphinx.util import strip_colors
+from sphinx.util.console import strip_colors
 from sphinx.util.fileutil import _template_basename, copy_asset, copy_asset_file
 
 
 class DummyTemplateLoader(BuiltinTemplateLoader):
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
         builder = mock.Mock()
         builder.config.templates_path = []

From 5f3846f8c6c3c40262ca02c733affc9ec8c71c23 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Thu, 3 Oct 2024 21:56:50 +0100
Subject: [PATCH 06/29] Improve testing for copyright year substitution
 (#12950)

---
 sphinx/config.py                              |   1 +
 .../roots/test-copyright-multiline/index.rst  |   3 -
 tests/roots/test-correct-year/conf.py         |   1 -
 tests/roots/test-correct-year/index.rst       |   4 -
 .../test_build_html_copyright.py              |  76 +++++++++
 tests/test_config/test_config.py              |  97 -----------
 tests/test_config/test_correct_year.py        | 159 +++++++++++++++++-
 7 files changed, 228 insertions(+), 113 deletions(-)
 delete mode 100644 tests/roots/test-correct-year/conf.py
 delete mode 100644 tests/roots/test-correct-year/index.rst
 create mode 100644 tests/test_builders/test_build_html_copyright.py

diff --git a/sphinx/config.py b/sphinx/config.py
index 0fd2102e732..3096cef0359 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -648,6 +648,7 @@ def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
     * ``YYYY``
     * ``YYYY,``
     * ``YYYY ``
+    * ``YYYY-YYYY``
     * ``YYYY-YYYY,``
     * ``YYYY-YYYY ``
 
diff --git a/tests/roots/test-copyright-multiline/index.rst b/tests/roots/test-copyright-multiline/index.rst
index aa32ae60f4a..e69de29bb2d 100644
--- a/tests/roots/test-copyright-multiline/index.rst
+++ b/tests/roots/test-copyright-multiline/index.rst
@@ -1,3 +0,0 @@
-========================
-test-copyright-multiline
-========================
diff --git a/tests/roots/test-correct-year/conf.py b/tests/roots/test-correct-year/conf.py
deleted file mode 100644
index 814c08b55e0..00000000000
--- a/tests/roots/test-correct-year/conf.py
+++ /dev/null
@@ -1 +0,0 @@
-copyright = '2006-2009, Author'
diff --git a/tests/roots/test-correct-year/index.rst b/tests/roots/test-correct-year/index.rst
deleted file mode 100644
index 938dfd50310..00000000000
--- a/tests/roots/test-correct-year/index.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-=================
-test-correct-year
-=================
-
diff --git a/tests/test_builders/test_build_html_copyright.py b/tests/test_builders/test_build_html_copyright.py
new file mode 100644
index 00000000000..2ddc50532aa
--- /dev/null
+++ b/tests/test_builders/test_build_html_copyright.py
@@ -0,0 +1,76 @@
+import time
+
+import pytest
+
+
+@pytest.fixture(
+    params=[
+        1293840000,  # 2011-01-01 00:00:00
+        1293839999,  # 2010-12-31 23:59:59
+    ]
+)
+def source_date_year(request, monkeypatch):
+    source_date_epoch = request.param
+    with monkeypatch.context() as m:
+        m.setenv('SOURCE_DATE_EPOCH', str(source_date_epoch))
+        yield time.gmtime(source_date_epoch).tm_year
+
+
+@pytest.mark.sphinx('html', testroot='copyright-multiline')
+def test_html_multi_line_copyright(app):
+    app.build(force_all=True)
+
+    content = (app.outdir / 'index.html').read_text(encoding='utf-8')
+
+    # check the copyright footer line by line (empty lines ignored)
+    assert '  &#169; Copyright 2006.<br/>\n' in content
+    assert '  &#169; Copyright 2006-2009, Alice.<br/>\n' in content
+    assert '  &#169; Copyright 2010-2013, Bob.<br/>\n' in content
+    assert '  &#169; Copyright 2014-2017, Charlie.<br/>\n' in content
+    assert '  &#169; Copyright 2018-2021, David.<br/>\n' in content
+    assert '  &#169; Copyright 2022-2025, Eve.' in content
+
+    # check the raw copyright footer block (empty lines included)
+    assert (
+        '      &#169; Copyright 2006.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2006-2009, Alice.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2010-2013, Bob.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2014-2017, Charlie.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2018-2021, David.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2022-2025, Eve.'
+    ) in content
+
+
+@pytest.mark.sphinx('html', testroot='copyright-multiline')
+def test_html_multi_line_copyright_sde(source_date_year, app):
+    app.build(force_all=True)
+
+    content = (app.outdir / 'index.html').read_text(encoding='utf-8')
+
+    # check the copyright footer line by line (empty lines ignored)
+    assert f'  &#169; Copyright {source_date_year}.<br/>\n' in content
+    assert f'  &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n' in content
+    assert f'  &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n' in content
+    assert f'  &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n' in content
+    assert f'  &#169; Copyright 2018-{source_date_year}, David.<br/>\n' in content
+    assert f'  &#169; Copyright 2022-{source_date_year}, Eve.' in content
+
+    # check the raw copyright footer block (empty lines included)
+    assert (
+        f'      &#169; Copyright {source_date_year}.<br/>\n'
+        f'    \n'
+        f'      &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n'
+        f'    \n'
+        f'      &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n'
+        f'    \n'
+        f'      &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n'
+        f'    \n'
+        f'      &#169; Copyright 2018-{source_date_year}, David.<br/>\n'
+        f'    \n'
+        f'      &#169; Copyright 2022-{source_date_year}, Eve.'
+    ) in content
diff --git a/tests/test_config/test_config.py b/tests/test_config/test_config.py
index 7f748f11e70..f1d6c12a0fd 100644
--- a/tests/test_config/test_config.py
+++ b/tests/test_config/test_config.py
@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import pickle
-import time
 from collections import Counter
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -18,7 +17,6 @@
     Config,
     _Opt,
     check_confval_types,
-    correct_copyright_year,
     is_serializable,
 )
 from sphinx.deprecation import RemovedInSphinx90Warning
@@ -741,101 +739,6 @@ def test_conf_py_nitpick_ignore_list(tmp_path):
     assert cfg.nitpick_ignore_regex == []
 
 
-@pytest.fixture(
-    params=[
-        # test with SOURCE_DATE_EPOCH unset: no modification
-        None,
-        # test with SOURCE_DATE_EPOCH set: copyright year should be updated
-        1293840000,
-        1293839999,
-    ]
-)
-def source_date_year(request, monkeypatch):
-    sde = request.param
-    with monkeypatch.context() as m:
-        if sde:
-            m.setenv('SOURCE_DATE_EPOCH', str(sde))
-            yield time.gmtime(sde).tm_year
-        else:
-            m.delenv('SOURCE_DATE_EPOCH', raising=False)
-            yield None
-
-
-@pytest.mark.sphinx('html', testroot='copyright-multiline')
-def test_multi_line_copyright(source_date_year, app):
-    app.build(force_all=True)
-
-    content = (app.outdir / 'index.html').read_text(encoding='utf-8')
-
-    if source_date_year is None:
-        # check the copyright footer line by line (empty lines ignored)
-        assert '  &#169; Copyright 2006.<br/>\n' in content
-        assert '  &#169; Copyright 2006-2009, Alice.<br/>\n' in content
-        assert '  &#169; Copyright 2010-2013, Bob.<br/>\n' in content
-        assert '  &#169; Copyright 2014-2017, Charlie.<br/>\n' in content
-        assert '  &#169; Copyright 2018-2021, David.<br/>\n' in content
-        assert '  &#169; Copyright 2022-2025, Eve.' in content
-
-        # check the raw copyright footer block (empty lines included)
-        assert (
-            '      &#169; Copyright 2006.<br/>\n'
-            '    \n'
-            '      &#169; Copyright 2006-2009, Alice.<br/>\n'
-            '    \n'
-            '      &#169; Copyright 2010-2013, Bob.<br/>\n'
-            '    \n'
-            '      &#169; Copyright 2014-2017, Charlie.<br/>\n'
-            '    \n'
-            '      &#169; Copyright 2018-2021, David.<br/>\n'
-            '    \n'
-            '      &#169; Copyright 2022-2025, Eve.'
-        ) in content
-    else:
-        # check the copyright footer line by line (empty lines ignored)
-        assert f'  &#169; Copyright {source_date_year}.<br/>\n' in content
-        assert f'  &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n' in content
-        assert f'  &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n' in content
-        assert f'  &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n' in content
-        assert f'  &#169; Copyright 2018-{source_date_year}, David.<br/>\n' in content
-        assert f'  &#169; Copyright 2022-{source_date_year}, Eve.' in content
-
-        # check the raw copyright footer block (empty lines included)
-        assert (
-            f'      &#169; Copyright {source_date_year}.<br/>\n'
-            f'    \n'
-            f'      &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n'
-            f'    \n'
-            f'      &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n'
-            f'    \n'
-            f'      &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n'
-            f'    \n'
-            f'      &#169; Copyright 2018-{source_date_year}, David.<br/>\n'
-            f'    \n'
-            f'      &#169; Copyright 2022-{source_date_year}, Eve.'
-        ) in content
-
-
-@pytest.mark.parametrize(
-    ('conf_copyright', 'expected_copyright'),
-    [
-        ('1970', '{current_year}'),
-        # https://github.com/sphinx-doc/sphinx/issues/11913
-        ('1970-1990', '1970-{current_year}'),
-        ('1970-1990 Alice', '1970-{current_year} Alice'),
-    ],
-)
-def test_correct_copyright_year(conf_copyright, expected_copyright, source_date_year):
-    config = Config({}, {'copyright': conf_copyright})
-    correct_copyright_year(_app=None, config=config)
-    actual_copyright = config['copyright']
-
-    if source_date_year is None:
-        expected_copyright = conf_copyright
-    else:
-        expected_copyright = expected_copyright.format(current_year=source_date_year)
-    assert actual_copyright == expected_copyright
-
-
 def test_gettext_compact_command_line_true():
     config = Config({}, {'gettext_compact': '1'})
     config.add('gettext_compact', True, '', {bool, str})
diff --git a/tests/test_config/test_correct_year.py b/tests/test_config/test_correct_year.py
index 815383dfaf4..4d0c70f32e4 100644
--- a/tests/test_config/test_correct_year.py
+++ b/tests/test_config/test_correct_year.py
@@ -1,20 +1,31 @@
 """Test copyright year adjustment"""
 
+import time
+
 import pytest
 
+from sphinx.config import Config, correct_copyright_year
+
+LT = time.localtime()
+LT_NEW = (2009, *LT[1:], LT.tm_zone, LT.tm_gmtoff)
+LOCALTIME_2009 = type(LT)(LT_NEW)
+
 
 @pytest.fixture(
     params=[
         # test with SOURCE_DATE_EPOCH unset: no modification
-        (None, '2006-2009'),
+        (None, ''),
         # test with SOURCE_DATE_EPOCH set: copyright year should be updated
-        ('1293840000', '2006-2011'),
-        ('1293839999', '2006-2010'),
+        ('1293840000', '2011'),
+        ('1293839999', '2010'),
+        ('1199145600', '2008'),
+        ('1199145599', '2007'),
     ],
 )
 def expect_date(request, monkeypatch):
     sde, expect = request.param
     with monkeypatch.context() as m:
+        m.setattr(time, 'localtime', lambda *a: LOCALTIME_2009)
         if sde:
             m.setenv('SOURCE_DATE_EPOCH', sde)
         else:
@@ -22,8 +33,140 @@ def expect_date(request, monkeypatch):
         yield expect
 
 
-@pytest.mark.sphinx('html', testroot='correct-year')
-def test_correct_year(expect_date, app):
-    app.build()
-    content = (app.outdir / 'index.html').read_text(encoding='utf8')
-    assert expect_date in content
+def test_correct_year(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2006-2009, Alice'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'2006-{expect_date}, Alice'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_space(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2006-2009 Alice'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'2006-{expect_date} Alice'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_no_author(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2006-2009'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'2006-{expect_date}'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_single(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2009, Alice'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'{expect_date}, Alice'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_single_space(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2009 Alice'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'{expect_date} Alice'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_single_no_author(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2009'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == f'{expect_date}'
+    else:
+        assert cfg.copyright == copyright_date
+
+
+def test_correct_year_multi_line(expect_date):
+    # test that copyright is substituted
+    copyright_dates = (
+        '2006',
+        '2006-2009, Alice',
+        '2010-2013, Bob',
+        '2014-2017, Charlie',
+        '2018-2021, David',
+        '2022-2025, Eve',
+    )
+    cfg = Config({'copyright': copyright_dates}, {})
+    assert cfg.copyright == copyright_dates
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == (
+            f'{expect_date}',
+            f'2006-{expect_date}, Alice',
+            f'2010-{expect_date}, Bob',
+            f'2014-{expect_date}, Charlie',
+            f'2018-{expect_date}, David',
+            f'2022-{expect_date}, Eve',
+        )
+    else:
+        assert cfg.copyright == copyright_dates
+
+
+def test_correct_year_multi_line_all_formats(expect_date):
+    # test that copyright is substituted
+    copyright_dates = (
+        '2009',
+        '2009 Alice',
+        '2009, Bob',
+        '2006-2009',
+        '2006-2009 Charlie',
+        '2006-2009, David',
+    )
+    cfg = Config({'copyright': copyright_dates}, {})
+    assert cfg.copyright == copyright_dates
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date:
+        assert cfg.copyright == (
+            f'{expect_date}',
+            f'{expect_date} Alice',
+            f'{expect_date}, Bob',
+            f'2006-{expect_date}',
+            f'2006-{expect_date} Charlie',
+            f'2006-{expect_date}, David',
+        )
+    else:
+        assert cfg.copyright == copyright_dates
+
+
+def test_correct_year_app(expect_date, tmp_path, make_app):
+    # integration test
+    copyright_date = '2006-2009, Alice'
+    (tmp_path / 'conf.py').touch()
+    app = make_app(
+        'dummy',
+        srcdir=tmp_path,
+        confoverrides={'copyright': copyright_date},
+    )
+    if expect_date:
+        assert app.config.copyright == f'2006-{expect_date}, Alice'
+    else:
+        assert app.config.copyright == copyright_date

From 5eb68b2bff559838e4bac2e30b4eabb2d1929d51 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Thu, 3 Oct 2024 22:20:55 +0100
Subject: [PATCH 07/29] Remove list of cross-reference roles

---
 doc/usage/referencing.rst | 20 --------------------
 1 file changed, 20 deletions(-)

diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst
index 02beaa6b80a..a3fccdc7ce1 100644
--- a/doc/usage/referencing.rst
+++ b/doc/usage/referencing.rst
@@ -49,26 +49,6 @@ The behavior can be modified in the following ways:
   (that is e.g. shown as a tool-tip on mouse-hover)
   will always be the full target name.
 
-Some of the built-in cross-reference roles are:
-
-* :rst:role:`:any: <any>`,
-  :rst:role:`:doc: <doc>`,
-  :rst:role:`:ref: <ref>`
-* :rst:role:`:confval: <confval>`,
-  :rst:role:`:envvar: <envvar>`,
-  :rst:role:`:option: <option>`
-* :rst:role:`:manpage: <manpage>`,
-  :rst:role:`:pep: <pep>`,
-  :rst:role:`:rfc: <rfc>`
-* :rst:role:`download`,
-  :rst:role:`:index: <index>`
-  :rst:role:`:numref: <numref>`,
-  :rst:role:`:keyword: <keyword>`,
-  :rst:role:`:term: <term>`,
-  :rst:role:`:token: <token>`
-* :rst:role:`!:func:`
-  (this uses the :confval:`primary_domain`, e.g. :rst:role:`:py:func: <py:func>`)
-* :ref:`Domain cross-reference roles <ref-objects>`
 
 .. _ref-objects:
 

From a84f7009acd4c51642e10a2cd15cea415860c0a7 Mon Sep 17 00:00:00 2001
From: James Addison <55152140+jayaddison@users.noreply.github.com>
Date: Fri, 4 Oct 2024 09:48:47 +0000
Subject: [PATCH 08/29] Restrict substitution of ``copyright`` years (#12516)

Only substitute copyright notice years with values from
``SOURCE_DATE_EPOCH`` for entries that match the current
system clock year, and disallow substitution of future years.

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
---
 CHANGES.rst                                   |  4 ++
 sphinx/config.py                              | 32 ++++++++++----
 .../test_build_html_copyright.py              | 39 +++++++++--------
 tests/test_config/test_correct_year.py        | 42 ++++++++++---------
 4 files changed, 72 insertions(+), 45 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index c1d0f410acb..55fb2cf8f6c 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -110,6 +110,10 @@ Bugs fixed
 * #12916: Restore support for custom templates named with the legacy ``_t``
   suffix during ``apidoc`` RST rendering (regression in 7.4.0).
   Patch by James Addison.
+* #12451: Only substitute copyright notice years with values from
+  ``SOURCE_DATE_EPOCH`` for entries that match the current system clock year,
+  and disallow substitution of future years.
+  Patch by James Addison and Adam Turner.
 
 Testing
 -------
diff --git a/sphinx/config.py b/sphinx/config.py
index 3096cef0359..5654eb2558f 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -625,22 +625,34 @@ def correct_copyright_year(_app: Sphinx, config: Config) -> None:
 
     See https://reproducible-builds.org/specs/source-date-epoch/
     """
-    if (source_date_epoch := getenv('SOURCE_DATE_EPOCH')) is None:
+    if source_date_epoch := int(getenv('SOURCE_DATE_EPOCH', '0')):
+        source_date_epoch_year = time.gmtime(source_date_epoch).tm_year
+    else:
         return
 
-    source_date_epoch_year = str(time.gmtime(int(source_date_epoch)).tm_year)
+    # If the current year is the replacement year, there's no work to do.
+    # We also skip replacement years that are in the future.
+    current_year = time.localtime().tm_year
+    if current_year <= source_date_epoch_year:
+        return
 
+    current_yr = str(current_year)
+    replace_yr = str(source_date_epoch_year)
     for k in ('copyright', 'epub_copyright'):
         if k in config:
             value: str | Sequence[str] = config[k]
             if isinstance(value, str):
-                config[k] = _substitute_copyright_year(value, source_date_epoch_year)
+                config[k] = _substitute_copyright_year(value, current_yr, replace_yr)
             else:
-                items = (_substitute_copyright_year(x, source_date_epoch_year) for x in value)
+                items = (
+                    _substitute_copyright_year(x, current_yr, replace_yr) for x in value
+                )
                 config[k] = type(value)(items)  # type: ignore[call-arg]
 
 
-def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
+def _substitute_copyright_year(
+    copyright_line: str, current_year: str, replace_year: str
+) -> str:
     """Replace the year in a single copyright line.
 
     Legal formats are:
@@ -657,13 +669,17 @@ def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
     if len(copyright_line) < 4 or not copyright_line[:4].isdigit():
         return copyright_line
 
-    if copyright_line[4:5] in {'', ' ', ','}:
+    if copyright_line[:4] == current_year and copyright_line[4:5] in {'', ' ', ','}:
         return replace_year + copyright_line[4:]
 
-    if copyright_line[4] != '-':
+    if copyright_line[4:5] != '-':
         return copyright_line
 
-    if copyright_line[5:9].isdigit() and copyright_line[9:10] in {'', ' ', ','}:
+    if (
+        copyright_line[5:9].isdigit()
+        and copyright_line[5:9] == current_year
+        and copyright_line[9:10] in {'', ' ', ','}
+    ):
         return copyright_line[:5] + replace_year + copyright_line[9:]
 
     return copyright_line
diff --git a/tests/test_builders/test_build_html_copyright.py b/tests/test_builders/test_build_html_copyright.py
index 2ddc50532aa..8e017ede4d7 100644
--- a/tests/test_builders/test_build_html_copyright.py
+++ b/tests/test_builders/test_build_html_copyright.py
@@ -2,16 +2,21 @@
 
 import pytest
 
+LT = time.localtime()
+LT_NEW = (2009, *LT[1:], LT.tm_zone, LT.tm_gmtoff)
+LOCALTIME_2009 = type(LT)(LT_NEW)
+
 
 @pytest.fixture(
     params=[
-        1293840000,  # 2011-01-01 00:00:00
-        1293839999,  # 2010-12-31 23:59:59
+        1199145600,  # 2008-01-01 00:00:00
+        1199145599,  # 2007-12-31 23:59:59
     ]
 )
 def source_date_year(request, monkeypatch):
     source_date_epoch = request.param
     with monkeypatch.context() as m:
+        m.setattr(time, 'localtime', lambda *a: LOCALTIME_2009)
         m.setenv('SOURCE_DATE_EPOCH', str(source_date_epoch))
         yield time.gmtime(source_date_epoch).tm_year
 
@@ -53,24 +58,24 @@ def test_html_multi_line_copyright_sde(source_date_year, app):
     content = (app.outdir / 'index.html').read_text(encoding='utf-8')
 
     # check the copyright footer line by line (empty lines ignored)
-    assert f'  &#169; Copyright {source_date_year}.<br/>\n' in content
+    assert '  &#169; Copyright 2006.<br/>\n' in content
     assert f'  &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n' in content
-    assert f'  &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n' in content
-    assert f'  &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n' in content
-    assert f'  &#169; Copyright 2018-{source_date_year}, David.<br/>\n' in content
-    assert f'  &#169; Copyright 2022-{source_date_year}, Eve.' in content
+    assert '  &#169; Copyright 2010-2013, Bob.<br/>\n' in content
+    assert '  &#169; Copyright 2014-2017, Charlie.<br/>\n' in content
+    assert '  &#169; Copyright 2018-2021, David.<br/>\n' in content
+    assert '  &#169; Copyright 2022-2025, Eve.' in content
 
     # check the raw copyright footer block (empty lines included)
     assert (
-        f'      &#169; Copyright {source_date_year}.<br/>\n'
-        f'    \n'
+        '      &#169; Copyright 2006.<br/>\n'
+        '    \n'
         f'      &#169; Copyright 2006-{source_date_year}, Alice.<br/>\n'
-        f'    \n'
-        f'      &#169; Copyright 2010-{source_date_year}, Bob.<br/>\n'
-        f'    \n'
-        f'      &#169; Copyright 2014-{source_date_year}, Charlie.<br/>\n'
-        f'    \n'
-        f'      &#169; Copyright 2018-{source_date_year}, David.<br/>\n'
-        f'    \n'
-        f'      &#169; Copyright 2022-{source_date_year}, Eve.'
+        '    \n'
+        '      &#169; Copyright 2010-2013, Bob.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2014-2017, Charlie.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2018-2021, David.<br/>\n'
+        '    \n'
+        '      &#169; Copyright 2022-2025, Eve.'
     ) in content
diff --git a/tests/test_config/test_correct_year.py b/tests/test_config/test_correct_year.py
index 4d0c70f32e4..7aafe5a66f5 100644
--- a/tests/test_config/test_correct_year.py
+++ b/tests/test_config/test_correct_year.py
@@ -14,12 +14,13 @@
 @pytest.fixture(
     params=[
         # test with SOURCE_DATE_EPOCH unset: no modification
-        (None, ''),
-        # test with SOURCE_DATE_EPOCH set: copyright year should be updated
-        ('1293840000', '2011'),
-        ('1293839999', '2010'),
-        ('1199145600', '2008'),
-        ('1199145599', '2007'),
+        (None, None),
+        # test with post-2009 SOURCE_DATE_EPOCH set: copyright year should not be updated
+        ('1293840000', 2011),
+        ('1293839999', 2010),
+        # test with pre-2009 SOURCE_DATE_EPOCH set: copyright year should be updated
+        ('1199145600', 2008),
+        ('1199145599', 2007),
     ],
 )
 def expect_date(request, monkeypatch):
@@ -39,7 +40,7 @@ def test_correct_year(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'2006-{expect_date}, Alice'
     else:
         assert cfg.copyright == copyright_date
@@ -51,7 +52,7 @@ def test_correct_year_space(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'2006-{expect_date} Alice'
     else:
         assert cfg.copyright == copyright_date
@@ -63,7 +64,7 @@ def test_correct_year_no_author(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'2006-{expect_date}'
     else:
         assert cfg.copyright == copyright_date
@@ -75,7 +76,7 @@ def test_correct_year_single(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'{expect_date}, Alice'
     else:
         assert cfg.copyright == copyright_date
@@ -87,7 +88,7 @@ def test_correct_year_single_space(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'{expect_date} Alice'
     else:
         assert cfg.copyright == copyright_date
@@ -99,7 +100,7 @@ def test_correct_year_single_no_author(expect_date):
     cfg = Config({'copyright': copyright_date}, {})
     assert cfg.copyright == copyright_date
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == f'{expect_date}'
     else:
         assert cfg.copyright == copyright_date
@@ -108,7 +109,7 @@ def test_correct_year_single_no_author(expect_date):
 def test_correct_year_multi_line(expect_date):
     # test that copyright is substituted
     copyright_dates = (
-        '2006',
+        '2009',
         '2006-2009, Alice',
         '2010-2013, Bob',
         '2014-2017, Charlie',
@@ -118,14 +119,15 @@ def test_correct_year_multi_line(expect_date):
     cfg = Config({'copyright': copyright_dates}, {})
     assert cfg.copyright == copyright_dates
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == (
             f'{expect_date}',
             f'2006-{expect_date}, Alice',
-            f'2010-{expect_date}, Bob',
-            f'2014-{expect_date}, Charlie',
-            f'2018-{expect_date}, David',
-            f'2022-{expect_date}, Eve',
+            # post 2009-dates aren't substituted
+            '2010-2013, Bob',
+            '2014-2017, Charlie',
+            '2018-2021, David',
+            '2022-2025, Eve',
         )
     else:
         assert cfg.copyright == copyright_dates
@@ -144,7 +146,7 @@ def test_correct_year_multi_line_all_formats(expect_date):
     cfg = Config({'copyright': copyright_dates}, {})
     assert cfg.copyright == copyright_dates
     correct_copyright_year(None, cfg)  # type: ignore[arg-type]
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert cfg.copyright == (
             f'{expect_date}',
             f'{expect_date} Alice',
@@ -166,7 +168,7 @@ def test_correct_year_app(expect_date, tmp_path, make_app):
         srcdir=tmp_path,
         confoverrides={'copyright': copyright_date},
     )
-    if expect_date:
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
         assert app.config.copyright == f'2006-{expect_date}, Alice'
     else:
         assert app.config.copyright == copyright_date

From dfa29f9d4a8c1690dd76670b80ec10bd120fd9e7 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 10:56:48 +0100
Subject: [PATCH 09/29] Add a missing word

---
 doc/usage/referencing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/usage/referencing.rst b/doc/usage/referencing.rst
index a3fccdc7ce1..6c18cf80ea8 100644
--- a/doc/usage/referencing.rst
+++ b/doc/usage/referencing.rst
@@ -41,7 +41,7 @@ The behavior can be modified in the following ways:
 
 * **Modified domain reference:**
   When :ref:`referencing domain objects <ref-objects>`,
-  a tilde ``~`` prefix shortens the link text the last component of the target.
+  a tilde ``~`` prefix shortens the link text to the last component of the target.
   For example, ``:py:meth:`~queue.Queue.get``` will
   refer to ``queue.Queue.get`` but only display ``get`` as the link text.
 

From 2bc662f0f83bd5bfffe14357c5013dc24efb6891 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 12:20:51 +0100
Subject: [PATCH 10/29] Shorten verbose metadata comments in templates

---
 sphinx/themes/agogo/layout.html          | 11 +----------
 sphinx/themes/basic/defindex.html        |  9 +--------
 sphinx/themes/basic/domainindex.html     | 10 +---------
 sphinx/themes/basic/genindex-single.html | 10 +---------
 sphinx/themes/basic/genindex-split.html  | 10 +---------
 sphinx/themes/basic/genindex.html        | 10 +---------
 sphinx/themes/basic/globaltoc.html       | 10 +---------
 sphinx/themes/basic/layout.html          | 10 +---------
 sphinx/themes/basic/localtoc.html        | 10 +---------
 sphinx/themes/basic/page.html            | 10 +---------
 sphinx/themes/basic/relations.html       | 10 +---------
 sphinx/themes/basic/search.html          | 10 +---------
 sphinx/themes/basic/searchbox.html       | 10 +---------
 sphinx/themes/basic/searchfield.html     | 14 ++++----------
 sphinx/themes/basic/sourcelink.html      | 10 +---------
 sphinx/themes/bizstyle/layout.html       | 10 +---------
 sphinx/themes/classic/layout.html        | 10 +---------
 sphinx/themes/epub/epub-cover.html       | 10 +---------
 sphinx/themes/epub/layout.html           | 10 +---------
 sphinx/themes/haiku/layout.html          | 10 +---------
 sphinx/themes/nonav/layout.html          | 10 +---------
 sphinx/themes/scrolls/layout.html        | 11 +----------
 22 files changed, 25 insertions(+), 200 deletions(-)

diff --git a/sphinx/themes/agogo/layout.html b/sphinx/themes/agogo/layout.html
index 9f5fabf3e13..92b7c41d48e 100644
--- a/sphinx/themes/agogo/layout.html
+++ b/sphinx/themes/agogo/layout.html
@@ -1,13 +1,4 @@
-{#
-    agogo/layout.html
-    ~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the agogo theme, originally written
-    by Andi Albrecht.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the agogo theme. #}
 {%- extends "basic/layout.html" %}
 
 {% block header %}
diff --git a/sphinx/themes/basic/defindex.html b/sphinx/themes/basic/defindex.html
index c614b69aa6b..f27e5ccf540 100644
--- a/sphinx/themes/basic/defindex.html
+++ b/sphinx/themes/basic/defindex.html
@@ -1,11 +1,4 @@
-{#
-    basic/defindex.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Default template for the "index" page.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+{# Default template for the "index" page.
 #}{{ warn('Now base template defindex.html is deprecated.') }}
 {%- extends "layout.html" %}
 {% set title = _('Overview') %}
diff --git a/sphinx/themes/basic/domainindex.html b/sphinx/themes/basic/domainindex.html
index 25d7e3002d3..f8e3305cda2 100644
--- a/sphinx/themes/basic/domainindex.html
+++ b/sphinx/themes/basic/domainindex.html
@@ -1,12 +1,4 @@
-{#
-    basic/domainindex.html
-    ~~~~~~~~~~~~~~~~~~~~~~
-
-    Template for domain indices (module index, ...).
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Template for domain indices (module index, ...). #}
 {%- extends "layout.html" %}
 {% set title = indextitle %}
 {% block extrahead %}
diff --git a/sphinx/themes/basic/genindex-single.html b/sphinx/themes/basic/genindex-single.html
index 79464dad6c0..af974149003 100644
--- a/sphinx/themes/basic/genindex-single.html
+++ b/sphinx/themes/basic/genindex-single.html
@@ -1,12 +1,4 @@
-{#
-    basic/genindex-single.html
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Template for a "single" page of a split index.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Template for a "single" page of a split index. #}
 {% macro indexentries(firstname, links) %}
   {%- if links -%}
     <a href="{{ links[0][1] }}">
diff --git a/sphinx/themes/basic/genindex-split.html b/sphinx/themes/basic/genindex-split.html
index 5375365e270..c2a10dec4d2 100644
--- a/sphinx/themes/basic/genindex-split.html
+++ b/sphinx/themes/basic/genindex-split.html
@@ -1,12 +1,4 @@
-{#
-    basic/genindex-split.html
-    ~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Template for a "split" index overview page.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Template for a "split" index overview page. #}
 {%- extends "layout.html" %}
 {% set title = _('Index') %}
 {% block body %}
diff --git a/sphinx/themes/basic/genindex.html b/sphinx/themes/basic/genindex.html
index b62a9c3db1a..c39b7493ee3 100644
--- a/sphinx/themes/basic/genindex.html
+++ b/sphinx/themes/basic/genindex.html
@@ -1,12 +1,4 @@
-{#
-    basic/genindex.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Template for an "all-in-one" index.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Template for an "all-in-one" index. #}
 {%- extends "layout.html" %}
 {% set title = _('Index') %}
 
diff --git a/sphinx/themes/basic/globaltoc.html b/sphinx/themes/basic/globaltoc.html
index 9745538f29d..d9173622633 100644
--- a/sphinx/themes/basic/globaltoc.html
+++ b/sphinx/themes/basic/globaltoc.html
@@ -1,11 +1,3 @@
-{#
-    basic/globaltoc.html
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Sphinx sidebar template: global table of contents.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx sidebar template: global table of contents. #}
 <h3><a href="{{ pathto(root_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
 {{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }}
diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html
index b438b919bfc..470e71d7d54 100644
--- a/sphinx/themes/basic/layout.html
+++ b/sphinx/themes/basic/layout.html
@@ -1,12 +1,4 @@
-{#
-    basic/layout.html
-    ~~~~~~~~~~~~~~~~~
-
-    Master layout template for Sphinx themes.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Master layout template for Sphinx themes. #}
 {%- block doctype -%}
 <!DOCTYPE html>
 {%- endblock %}
diff --git a/sphinx/themes/basic/localtoc.html b/sphinx/themes/basic/localtoc.html
index 70f3e160b37..ddebfebaeb6 100644
--- a/sphinx/themes/basic/localtoc.html
+++ b/sphinx/themes/basic/localtoc.html
@@ -1,12 +1,4 @@
-{#
-    basic/localtoc.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Sphinx sidebar template: local table of contents.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx sidebar template: local table of contents. #}
 {%- if display_toc %}
   <div>
     <h3><a href="{{ pathto(root_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
diff --git a/sphinx/themes/basic/page.html b/sphinx/themes/basic/page.html
index 502278e7f6e..19a1c876efb 100644
--- a/sphinx/themes/basic/page.html
+++ b/sphinx/themes/basic/page.html
@@ -1,12 +1,4 @@
-{#
-    basic/page.html
-    ~~~~~~~~~~~~~~~
-
-    Master template for simple pages.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Master template for simple pages. #}
 {%- extends "layout.html" %}
 {% block body %}
   {{ body }}
diff --git a/sphinx/themes/basic/relations.html b/sphinx/themes/basic/relations.html
index 7ce494f3460..f142688bb04 100644
--- a/sphinx/themes/basic/relations.html
+++ b/sphinx/themes/basic/relations.html
@@ -1,12 +1,4 @@
-{#
-    basic/relations.html
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Sphinx sidebar template: relation links.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx sidebar template: relation links. #}
 {%- if prev %}
   <div>
     <h4>{{ _('Previous topic') }}</h4>
diff --git a/sphinx/themes/basic/search.html b/sphinx/themes/basic/search.html
index 8bad82a51be..0ce54c43424 100644
--- a/sphinx/themes/basic/search.html
+++ b/sphinx/themes/basic/search.html
@@ -1,12 +1,4 @@
-{#
-    basic/search.html
-    ~~~~~~~~~~~~~~~~~
-
-    Template for the search page.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Template for the search page. #}
 {%- extends "layout.html" %}
 {% set title = _('Search') %}
 {%- block scripts %}
diff --git a/sphinx/themes/basic/searchbox.html b/sphinx/themes/basic/searchbox.html
index 1f084bb926e..e0045b4de26 100644
--- a/sphinx/themes/basic/searchbox.html
+++ b/sphinx/themes/basic/searchbox.html
@@ -1,12 +1,4 @@
-{#
-    basic/searchbox.html
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Sphinx sidebar template: quick search box.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx sidebar template: quick search box. #}
 {%- if pagename != "search" and builder != "singlehtml" %}
 <search id="searchbox" style="display: none" role="search">
   <h3 id="searchlabel">{{ _('Quick search') }}</h3>
diff --git a/sphinx/themes/basic/searchfield.html b/sphinx/themes/basic/searchfield.html
index 396218ff53f..cffde75a86f 100644
--- a/sphinx/themes/basic/searchfield.html
+++ b/sphinx/themes/basic/searchfield.html
@@ -1,14 +1,8 @@
-{#
-    basic/searchfield.html
-    ~~~~~~~~~~~~~~~~~~~~~~
+{# Sphinx sidebar template: search field.
 
-    Sphinx sidebar template: search field.
-    This component is similar to searchbox.html but does not include an
-    extra heading ("Quick search"). Instead, it uses a placeholder text
-    in the search field.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+This component is similar to searchbox.html but does not include an
+extra heading ("Quick search"). Instead, it uses a placeholder text
+in the search field.
 #}
 {%- if pagename != "search" and builder != "singlehtml" %}
 <search id="searchbox" style="display: none" role="search">
diff --git a/sphinx/themes/basic/sourcelink.html b/sphinx/themes/basic/sourcelink.html
index 72a59666de8..14bf7cad4c8 100644
--- a/sphinx/themes/basic/sourcelink.html
+++ b/sphinx/themes/basic/sourcelink.html
@@ -1,12 +1,4 @@
-{#
-    basic/sourcelink.html
-    ~~~~~~~~~~~~~~~~~~~~~
-
-    Sphinx sidebar template: "show source" link.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx sidebar template: "show source" link. #}
 {%- if show_source and has_source and sourcename %}
   <div role="note" aria-label="source link">
     <h3>{{ _('This Page') }}</h3>
diff --git a/sphinx/themes/bizstyle/layout.html b/sphinx/themes/bizstyle/layout.html
index 226c7878d9c..a19309056ff 100644
--- a/sphinx/themes/bizstyle/layout.html
+++ b/sphinx/themes/bizstyle/layout.html
@@ -1,12 +1,4 @@
-{#
-    bizstyle/layout.html
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the bizstyle theme.
-
-    :copyright: Copyright 2007-2024 by Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the bizstyle theme. #}
 {% extends "basic/layout.html" %}
 
 {%- block scripts %}
diff --git a/sphinx/themes/classic/layout.html b/sphinx/themes/classic/layout.html
index 99a101c96c9..d2fc9270e39 100644
--- a/sphinx/themes/classic/layout.html
+++ b/sphinx/themes/classic/layout.html
@@ -1,12 +1,4 @@
-{#
-    classic/layout.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the classic theme.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the classic theme. #}
 {%- extends "basic/layout.html" %}
 
 {%- block scripts %}
diff --git a/sphinx/themes/epub/epub-cover.html b/sphinx/themes/epub/epub-cover.html
index 15d46161b60..5682f262ea8 100644
--- a/sphinx/themes/epub/epub-cover.html
+++ b/sphinx/themes/epub/epub-cover.html
@@ -1,12 +1,4 @@
-{#
-    epub/epub-cover.html
-    ~~~~~~~~~~~~~~~~~~~~
-
-    Sample template for the html cover page.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sample template for the html cover page. #}
 {%- extends "layout.html" %}
 {%- block header %}{% endblock %}
 {%- block rootrellink %}{% endblock %}
diff --git a/sphinx/themes/epub/layout.html b/sphinx/themes/epub/layout.html
index c7b63cd8108..2938d0b3c95 100644
--- a/sphinx/themes/epub/layout.html
+++ b/sphinx/themes/epub/layout.html
@@ -1,12 +1,4 @@
-{#
-    epub/layout.html
-    ~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the epub theme.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the epub theme. #}
 {%- extends "basic/layout.html" %}
 
 {%- block doctype -%}
diff --git a/sphinx/themes/haiku/layout.html b/sphinx/themes/haiku/layout.html
index b23937fbb6c..0c13802c10f 100644
--- a/sphinx/themes/haiku/layout.html
+++ b/sphinx/themes/haiku/layout.html
@@ -1,12 +1,4 @@
-{#
-    haiku/layout.html
-    ~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the haiku theme.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the haiku theme. #}
 {%- extends "basic/layout.html" %}
 
 {# do not display relbars #}
diff --git a/sphinx/themes/nonav/layout.html b/sphinx/themes/nonav/layout.html
index ba5f7b74603..f61ef14366a 100644
--- a/sphinx/themes/nonav/layout.html
+++ b/sphinx/themes/nonav/layout.html
@@ -1,12 +1,4 @@
-{#
-    nonav/layout.html
-    ~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the any help system theme.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the any help system theme. #}
 {%- extends "basic/layout.html" %}
 
 {%- block doctype -%}
diff --git a/sphinx/themes/scrolls/layout.html b/sphinx/themes/scrolls/layout.html
index 8a0db7d12bb..a0a5e046530 100644
--- a/sphinx/themes/scrolls/layout.html
+++ b/sphinx/themes/scrolls/layout.html
@@ -1,13 +1,4 @@
-{#
-    scrolls/layout.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the scrolls theme, originally written
-    by Armin Ronacher.
-
-    :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
+{# Sphinx layout template for the scrolls theme. #}
 {%- extends "basic/layout.html" %}
 {%- block css %}
     {{ super() }}

From 45273f292e8d5c746c43bb8b6048ddfd4d7c8d62 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 12:27:26 +0100
Subject: [PATCH 11/29] Remove titles from theme assets

---
 sphinx/templates/graphviz/graphviz.css        |  3 ---
 sphinx/themes/agogo/static/agogo.css.jinja    |  3 ---
 sphinx/themes/basic/static/basic.css.jinja    |  3 ---
 sphinx/themes/basic/static/doctools.js        |  3 ---
 .../basic/static/language_data.js.jinja       |  3 ---
 sphinx/themes/basic/static/searchtools.js     |  3 ---
 .../themes/bizstyle/static/bizstyle.css.jinja |  5 +----
 .../themes/bizstyle/static/bizstyle.js.jinja  | 20 +++++++++----------
 .../themes/classic/static/classic.css.jinja   |  3 ---
 sphinx/themes/classic/static/sidebar.js.jinja |  3 ---
 sphinx/themes/epub/static/epub.css.jinja      |  3 ---
 sphinx/themes/haiku/static/haiku.css.jinja    |  3 ---
 sphinx/themes/nature/static/nature.css.jinja  |  3 ---
 sphinx/themes/nonav/static/nonav.css.jinja    |  3 ---
 sphinx/themes/pyramid/static/epub.css.jinja   |  3 ---
 .../themes/pyramid/static/pyramid.css.jinja   |  3 ---
 .../themes/scrolls/static/scrolls.css.jinja   |  3 ---
 .../sphinxdoc/static/sphinxdoc.css.jinja      |  7 ++-----
 .../traditional/static/traditional.css.jinja  |  3 ---
 tests/js/language_data.js                     |  3 ---
 20 files changed, 12 insertions(+), 71 deletions(-)

diff --git a/sphinx/templates/graphviz/graphviz.css b/sphinx/templates/graphviz/graphviz.css
index 027576e34d2..a92013eda61 100644
--- a/sphinx/templates/graphviz/graphviz.css
+++ b/sphinx/templates/graphviz/graphviz.css
@@ -1,7 +1,4 @@
 /*
- * graphviz.css
- * ~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- graphviz extension.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/agogo/static/agogo.css.jinja b/sphinx/themes/agogo/static/agogo.css.jinja
index 3b7a1d0b8f4..8fa2d026814 100644
--- a/sphinx/themes/agogo/static/agogo.css.jinja
+++ b/sphinx/themes/agogo/static/agogo.css.jinja
@@ -1,7 +1,4 @@
 /*
- * agogo.css_t
- * ~~~~~~~~~~~
- *
  * Sphinx stylesheet -- agogo theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/basic/static/basic.css.jinja b/sphinx/themes/basic/static/basic.css.jinja
index 53fbadb0b6a..6597c9cc14d 100644
--- a/sphinx/themes/basic/static/basic.css.jinja
+++ b/sphinx/themes/basic/static/basic.css.jinja
@@ -1,7 +1,4 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/basic/static/doctools.js b/sphinx/themes/basic/static/doctools.js
index 4d67807d17d..ae3096b3be5 100644
--- a/sphinx/themes/basic/static/doctools.js
+++ b/sphinx/themes/basic/static/doctools.js
@@ -1,7 +1,4 @@
 /*
- * doctools.js
- * ~~~~~~~~~~~
- *
  * Base JavaScript utilities for all Sphinx HTML documentation.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/basic/static/language_data.js.jinja b/sphinx/themes/basic/static/language_data.js.jinja
index 3666e5e6f03..38a1d72277d 100644
--- a/sphinx/themes/basic/static/language_data.js.jinja
+++ b/sphinx/themes/basic/static/language_data.js.jinja
@@ -1,7 +1,4 @@
 /*
- * language_data.js
- * ~~~~~~~~~~~~~~~~
- *
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
  *
diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js
index e89bfc3aebf..e7dbe23ddfd 100644
--- a/sphinx/themes/basic/static/searchtools.js
+++ b/sphinx/themes/basic/static/searchtools.js
@@ -1,7 +1,4 @@
 /*
- * searchtools.js
- * ~~~~~~~~~~~~~~~~
- *
  * Sphinx JavaScript utilities for the full-text search.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/bizstyle/static/bizstyle.css.jinja b/sphinx/themes/bizstyle/static/bizstyle.css.jinja
index 9630fbcd8cd..ad0d8525599 100644
--- a/sphinx/themes/bizstyle/static/bizstyle.css.jinja
+++ b/sphinx/themes/bizstyle/static/bizstyle.css.jinja
@@ -1,10 +1,7 @@
 /*
- * bizstyle.css_t
- * ~~~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- business style theme.
  *
- * :copyright: Copyright 2007-2024 by Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
diff --git a/sphinx/themes/bizstyle/static/bizstyle.js.jinja b/sphinx/themes/bizstyle/static/bizstyle.js.jinja
index 1373b22a9f7..7e1f3311b07 100644
--- a/sphinx/themes/bizstyle/static/bizstyle.js.jinja
+++ b/sphinx/themes/bizstyle/static/bizstyle.js.jinja
@@ -1,14 +1,12 @@
-//
-// bizstyle.js
-// ~~~~~~~~~~~
-//
-// Sphinx javascript -- for bizstyle theme.
-//
-// This theme was created by referring to 'sphinxdoc'
-//
-// :copyright: Copyright 2007-2024 by Sphinx team, see AUTHORS.
-// :license: BSD, see LICENSE for details.
-//
+/*
+ * Sphinx javascript -- for bizstyle theme.
+ *
+ * This theme was created by referring to 'sphinxdoc'
+ *
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
 const initialiseBizStyle = () => {
     if (navigator.userAgent.indexOf("iPhone") > 0 || navigator.userAgent.indexOf("Android") > 0) {
         document.querySelector("li.nav-item-0 a").innerText = "Top"
diff --git a/sphinx/themes/classic/static/classic.css.jinja b/sphinx/themes/classic/static/classic.css.jinja
index 78429fcd6d2..a4dd600ae49 100644
--- a/sphinx/themes/classic/static/classic.css.jinja
+++ b/sphinx/themes/classic/static/classic.css.jinja
@@ -1,7 +1,4 @@
 /*
- * classic.css_t
- * ~~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- classic theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/classic/static/sidebar.js.jinja b/sphinx/themes/classic/static/sidebar.js.jinja
index 205e1dcfe99..18524efb11b 100644
--- a/sphinx/themes/classic/static/sidebar.js.jinja
+++ b/sphinx/themes/classic/static/sidebar.js.jinja
@@ -1,7 +1,4 @@
 /*
- * sidebar.js
- * ~~~~~~~~~~
- *
  * This script makes the Sphinx sidebar collapsible.
  *
  * .sphinxsidebar contains .sphinxsidebarwrapper.  This script adds
diff --git a/sphinx/themes/epub/static/epub.css.jinja b/sphinx/themes/epub/static/epub.css.jinja
index 75b45df2272..035a13730bc 100644
--- a/sphinx/themes/epub/static/epub.css.jinja
+++ b/sphinx/themes/epub/static/epub.css.jinja
@@ -1,7 +1,4 @@
 /*
- * epub.css_t
- * ~~~~~~~~~~
- *
  * Sphinx stylesheet -- epub theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/haiku/static/haiku.css.jinja b/sphinx/themes/haiku/static/haiku.css.jinja
index ce449b5d00a..f97984dc81d 100644
--- a/sphinx/themes/haiku/static/haiku.css.jinja
+++ b/sphinx/themes/haiku/static/haiku.css.jinja
@@ -1,7 +1,4 @@
 /*
- * haiku.css_t
- * ~~~~~~~~~~~
- *
  * Sphinx stylesheet -- haiku theme.
  *
  * Adapted from https://haiku-os.org/docs/Haiku-doc.css.
diff --git a/sphinx/themes/nature/static/nature.css.jinja b/sphinx/themes/nature/static/nature.css.jinja
index e2a96064e59..5765f1f0a29 100644
--- a/sphinx/themes/nature/static/nature.css.jinja
+++ b/sphinx/themes/nature/static/nature.css.jinja
@@ -1,7 +1,4 @@
 /*
- * nature.css_t
- * ~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- nature theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/nonav/static/nonav.css.jinja b/sphinx/themes/nonav/static/nonav.css.jinja
index 5e76c0e0096..230f27fbdf3 100644
--- a/sphinx/themes/nonav/static/nonav.css.jinja
+++ b/sphinx/themes/nonav/static/nonav.css.jinja
@@ -1,7 +1,4 @@
 /*
- * nonav.css
- * ~~~~~~~~~~
- *
  * Sphinx stylesheet -- nonav theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/pyramid/static/epub.css.jinja b/sphinx/themes/pyramid/static/epub.css.jinja
index 43f82cdf510..93e630d768b 100644
--- a/sphinx/themes/pyramid/static/epub.css.jinja
+++ b/sphinx/themes/pyramid/static/epub.css.jinja
@@ -1,7 +1,4 @@
 /*
- * default.css_t
- * ~~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- default theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/pyramid/static/pyramid.css.jinja b/sphinx/themes/pyramid/static/pyramid.css.jinja
index 5283e94b679..3c06dcfee73 100644
--- a/sphinx/themes/pyramid/static/pyramid.css.jinja
+++ b/sphinx/themes/pyramid/static/pyramid.css.jinja
@@ -1,7 +1,4 @@
 /*
- * pyramid.css_t
- * ~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- pylons theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/scrolls/static/scrolls.css.jinja b/sphinx/themes/scrolls/static/scrolls.css.jinja
index a1596890bf3..38d2bb1b28c 100644
--- a/sphinx/themes/scrolls/static/scrolls.css.jinja
+++ b/sphinx/themes/scrolls/static/scrolls.css.jinja
@@ -1,7 +1,4 @@
 /*
- * scrolls.css_t
- * ~~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- scrolls theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja b/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
index 3cfd3104b2d..094b7390719 100644
--- a/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
+++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
@@ -1,9 +1,6 @@
 /*
- * sphinxdoc.css_t
- * ~~~~~~~~~~~~~~~
- *
- * Sphinx stylesheet -- sphinxdoc theme.  Originally created by
- * Armin Ronacher for Werkzeug.
+ * Sphinx stylesheet -- sphinxdoc theme.
+ * Originally created by Armin Ronacher for Werkzeug.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
diff --git a/sphinx/themes/traditional/static/traditional.css.jinja b/sphinx/themes/traditional/static/traditional.css.jinja
index 9ddac53e01a..968c6844dee 100644
--- a/sphinx/themes/traditional/static/traditional.css.jinja
+++ b/sphinx/themes/traditional/static/traditional.css.jinja
@@ -1,7 +1,4 @@
 /*
- * traditional.css
- * ~~~~~~~~~~~~~~~
- *
  * Sphinx stylesheet -- traditional docs.python.org theme.
  *
  * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
diff --git a/tests/js/language_data.js b/tests/js/language_data.js
index 89083d9ec7c..5dcd03aa72e 100644
--- a/tests/js/language_data.js
+++ b/tests/js/language_data.js
@@ -1,7 +1,4 @@
 /*
- * language_data.js
- * ~~~~~~~~~~~~~~~~
- *
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
  *

From 7195d9a662dda7150f63ff166fcf03f43f7d4c8a Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 12:31:45 +0100
Subject: [PATCH 12/29] Remove copyright and licence comments from theme asset
 files

---
 sphinx/templates/graphviz/graphviz.css                 | 4 ----
 sphinx/themes/agogo/static/agogo.css.jinja             | 4 ----
 sphinx/themes/basic/static/basic.css.jinja             | 4 ----
 sphinx/themes/basic/static/doctools.js                 | 4 ----
 sphinx/themes/basic/static/language_data.js.jinja      | 4 ----
 sphinx/themes/basic/static/searchtools.js              | 4 ----
 sphinx/themes/bizstyle/static/bizstyle.css.jinja       | 4 ----
 sphinx/themes/bizstyle/static/bizstyle.js.jinja        | 4 ----
 sphinx/themes/classic/static/classic.css.jinja         | 4 ----
 sphinx/themes/classic/static/sidebar.js.jinja          | 3 ---
 sphinx/themes/epub/static/epub.css.jinja               | 4 ----
 sphinx/themes/haiku/static/haiku.css.jinja             | 3 ---
 sphinx/themes/nature/static/nature.css.jinja           | 4 ----
 sphinx/themes/nonav/static/nonav.css.jinja             | 4 ----
 sphinx/themes/pyramid/static/epub.css.jinja            | 4 ----
 sphinx/themes/pyramid/static/pyramid.css.jinja         | 4 ----
 sphinx/themes/scrolls/static/scrolls.css.jinja         | 4 ----
 sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja     | 4 +---
 sphinx/themes/traditional/static/traditional.css.jinja | 4 ----
 tests/js/language_data.js                              | 4 ----
 20 files changed, 1 insertion(+), 77 deletions(-)

diff --git a/sphinx/templates/graphviz/graphviz.css b/sphinx/templates/graphviz/graphviz.css
index a92013eda61..30f3837b62a 100644
--- a/sphinx/templates/graphviz/graphviz.css
+++ b/sphinx/templates/graphviz/graphviz.css
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- graphviz extension.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 img.graphviz {
diff --git a/sphinx/themes/agogo/static/agogo.css.jinja b/sphinx/themes/agogo/static/agogo.css.jinja
index 8fa2d026814..d281c744d3c 100644
--- a/sphinx/themes/agogo/static/agogo.css.jinja
+++ b/sphinx/themes/agogo/static/agogo.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- agogo theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 * {
diff --git a/sphinx/themes/basic/static/basic.css.jinja b/sphinx/themes/basic/static/basic.css.jinja
index 6597c9cc14d..4a00f3629f0 100644
--- a/sphinx/themes/basic/static/basic.css.jinja
+++ b/sphinx/themes/basic/static/basic.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
diff --git a/sphinx/themes/basic/static/doctools.js b/sphinx/themes/basic/static/doctools.js
index ae3096b3be5..0398ebb9f03 100644
--- a/sphinx/themes/basic/static/doctools.js
+++ b/sphinx/themes/basic/static/doctools.js
@@ -1,9 +1,5 @@
 /*
  * Base JavaScript utilities for all Sphinx HTML documentation.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 
diff --git a/sphinx/themes/basic/static/language_data.js.jinja b/sphinx/themes/basic/static/language_data.js.jinja
index 38a1d72277d..64aefa798c7 100644
--- a/sphinx/themes/basic/static/language_data.js.jinja
+++ b/sphinx/themes/basic/static/language_data.js.jinja
@@ -1,10 +1,6 @@
 /*
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 var stopwords = {{ search_language_stop_words }};
diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js
index e7dbe23ddfd..2c774d17aff 100644
--- a/sphinx/themes/basic/static/searchtools.js
+++ b/sphinx/themes/basic/static/searchtools.js
@@ -1,9 +1,5 @@
 /*
  * Sphinx JavaScript utilities for the full-text search.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 
diff --git a/sphinx/themes/bizstyle/static/bizstyle.css.jinja b/sphinx/themes/bizstyle/static/bizstyle.css.jinja
index ad0d8525599..771b99fa54c 100644
--- a/sphinx/themes/bizstyle/static/bizstyle.css.jinja
+++ b/sphinx/themes/bizstyle/static/bizstyle.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- business style theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/bizstyle/static/bizstyle.js.jinja b/sphinx/themes/bizstyle/static/bizstyle.js.jinja
index 7e1f3311b07..47d2b8dccb6 100644
--- a/sphinx/themes/bizstyle/static/bizstyle.js.jinja
+++ b/sphinx/themes/bizstyle/static/bizstyle.js.jinja
@@ -2,10 +2,6 @@
  * Sphinx javascript -- for bizstyle theme.
  *
  * This theme was created by referring to 'sphinxdoc'
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 const initialiseBizStyle = () => {
     if (navigator.userAgent.indexOf("iPhone") > 0 || navigator.userAgent.indexOf("Android") > 0) {
diff --git a/sphinx/themes/classic/static/classic.css.jinja b/sphinx/themes/classic/static/classic.css.jinja
index a4dd600ae49..24b67fa76ed 100644
--- a/sphinx/themes/classic/static/classic.css.jinja
+++ b/sphinx/themes/classic/static/classic.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- classic theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/classic/static/sidebar.js.jinja b/sphinx/themes/classic/static/sidebar.js.jinja
index 18524efb11b..adf2b6636ff 100644
--- a/sphinx/themes/classic/static/sidebar.js.jinja
+++ b/sphinx/themes/classic/static/sidebar.js.jinja
@@ -13,9 +13,6 @@
  * Once the browser is closed the cookie is deleted and the position
  * reset to the default (expanded).
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 const initialiseSidebar = () => {
diff --git a/sphinx/themes/epub/static/epub.css.jinja b/sphinx/themes/epub/static/epub.css.jinja
index 035a13730bc..306016bd301 100644
--- a/sphinx/themes/epub/static/epub.css.jinja
+++ b/sphinx/themes/epub/static/epub.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- epub theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
diff --git a/sphinx/themes/haiku/static/haiku.css.jinja b/sphinx/themes/haiku/static/haiku.css.jinja
index f97984dc81d..676e34ceeaf 100644
--- a/sphinx/themes/haiku/static/haiku.css.jinja
+++ b/sphinx/themes/haiku/static/haiku.css.jinja
@@ -13,9 +13,6 @@
  *              Braden Ewing <brewin@gmail.com>
  *              Humdinger <humdingerb@gmail.com>
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/nature/static/nature.css.jinja b/sphinx/themes/nature/static/nature.css.jinja
index 5765f1f0a29..3c8205382c6 100644
--- a/sphinx/themes/nature/static/nature.css.jinja
+++ b/sphinx/themes/nature/static/nature.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- nature theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/nonav/static/nonav.css.jinja b/sphinx/themes/nonav/static/nonav.css.jinja
index 230f27fbdf3..f68ff88dcd6 100644
--- a/sphinx/themes/nonav/static/nonav.css.jinja
+++ b/sphinx/themes/nonav/static/nonav.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- nonav theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
diff --git a/sphinx/themes/pyramid/static/epub.css.jinja b/sphinx/themes/pyramid/static/epub.css.jinja
index 93e630d768b..cef087ced01 100644
--- a/sphinx/themes/pyramid/static/epub.css.jinja
+++ b/sphinx/themes/pyramid/static/epub.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- default theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/pyramid/static/pyramid.css.jinja b/sphinx/themes/pyramid/static/pyramid.css.jinja
index 3c06dcfee73..9d631f7ad88 100644
--- a/sphinx/themes/pyramid/static/pyramid.css.jinja
+++ b/sphinx/themes/pyramid/static/pyramid.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- pylons theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 @import url("basic.css");
diff --git a/sphinx/themes/scrolls/static/scrolls.css.jinja b/sphinx/themes/scrolls/static/scrolls.css.jinja
index 38d2bb1b28c..401449b8d9d 100644
--- a/sphinx/themes/scrolls/static/scrolls.css.jinja
+++ b/sphinx/themes/scrolls/static/scrolls.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- scrolls theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 body {
diff --git a/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja b/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
index 094b7390719..07a0166d012 100644
--- a/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
+++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css.jinja
@@ -1,9 +1,7 @@
 /*
  * Sphinx stylesheet -- sphinxdoc theme.
- * Originally created by Armin Ronacher for Werkzeug.
  *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
+ * Originally created by Armin Ronacher for Werkzeug.
  *
  */
 
diff --git a/sphinx/themes/traditional/static/traditional.css.jinja b/sphinx/themes/traditional/static/traditional.css.jinja
index 968c6844dee..c5e829786d0 100644
--- a/sphinx/themes/traditional/static/traditional.css.jinja
+++ b/sphinx/themes/traditional/static/traditional.css.jinja
@@ -1,9 +1,5 @@
 /*
  * Sphinx stylesheet -- traditional docs.python.org theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 body {
diff --git a/tests/js/language_data.js b/tests/js/language_data.js
index 5dcd03aa72e..15e4a8447f0 100644
--- a/tests/js/language_data.js
+++ b/tests/js/language_data.js
@@ -1,10 +1,6 @@
 /*
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 var stopwords = [];

From 3677dd1bca90551f6864485b8d86210020a8ea23 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 12:33:03 +0100
Subject: [PATCH 13/29] Shorten ``copyright`` in the ChangesBuilder tests

---
 tests/roots/test-changes/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/roots/test-changes/conf.py b/tests/roots/test-changes/conf.py
index 29bea6a1724..08ee85d672f 100644
--- a/tests/roots/test-changes/conf.py
+++ b/tests/roots/test-changes/conf.py
@@ -1,4 +1,4 @@
 project = 'Sphinx ChangesBuilder tests'
-copyright = '2007-2024 by the Sphinx team, see AUTHORS'
+copyright = '2007'
 version = '0.6'
 release = '0.6alpha1'

From be52db2bb3d68674fe32bcd582ebedd3b8a6ff16 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 13:52:29 +0100
Subject: [PATCH 14/29] Support placeholders for years in copyright (#12910)

---
 CHANGES.rst                                   |  6 ++
 doc/conf.py                                   |  3 +-
 doc/usage/configuration.rst                   | 14 +++++
 sphinx/config.py                              | 16 +++++
 ...test_correct_year.py => test_copyright.py} | 60 ++++++++++++++++++-
 5 files changed, 96 insertions(+), 3 deletions(-)
 rename tests/test_config/{test_correct_year.py => test_copyright.py} (74%)

diff --git a/CHANGES.rst b/CHANGES.rst
index 55fb2cf8f6c..f0c3246d070 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -53,6 +53,12 @@ Features added
   GMT (universal time) instead of local time for the date-time
   supplied to :confval:`html_last_updated_fmt`.
   Patch by Adam Turner.
+* #12910: Copyright entries now support the ``'%Y'`` placeholder
+  to substitute the current year.
+  This is helpful for reducing the reliance on Python modules
+  such as :py:mod:`time` or :py:mod:`datetime` in :file:`conf.py`.
+  See :ref:`the docs <config-copyright>` for further detail.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
diff --git a/doc/conf.py b/doc/conf.py
index 6980eb91595..f4a6d9948eb 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -3,7 +3,6 @@
 
 import os
 import re
-import time
 from typing import TYPE_CHECKING
 
 from sphinx import __display_version__
@@ -27,7 +26,7 @@
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
+copyright = '2007-%Y, the Sphinx developers'
 release = version = __display_version__
 show_authors = True
 nitpicky = True
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index be6edee7d7c..d80d40a8265 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -114,6 +114,8 @@ Project information
 
       author = 'Joe Bloggs'
 
+.. _config-copyright:
+
 .. confval:: copyright
              project_copyright
    :type: :code-py:`str | Sequence[str]`
@@ -128,6 +130,14 @@ Project information
    * :code-py:`copyright = 'YYYY-YYYY, Author Name'`
    * :code-py:`copyright = 'YYYY-YYYY Author Name'`
 
+   If the string :code-py:`'%Y'` appears in a copyright line,
+   it will be replaced with the current four-digit year.
+   For example:
+
+   * :code-py:`copyright = '%Y'`
+   * :code-py:`copyright = '%Y, Author Name'`
+   * :code-py:`copyright = 'YYYY-%Y, Author Name'`
+
    .. versionadded:: 3.5
       The :code-py:`project_copyright` alias.
 
@@ -135,6 +145,9 @@ Project information
       The value may now be a sequence of copyright statements in the above form,
       which will be displayed each to their own line.
 
+   .. versionchanged:: 8.1
+      Copyright statements support the :code-py:`'%Y'` placeholder.
+
 .. confval:: version
    :type: :code-py:`str`
    :default: :code-py:`''`
@@ -2528,6 +2541,7 @@ so the HTML options also apply where appropriate.
    :default: The value of **copyright**
 
    The copyright of the document.
+   See :confval:`copyright` for permitted formats.
 
 .. confval:: epub_identifier
    :type: :code-py:`str`
diff --git a/sphinx/config.py b/sphinx/config.py
index 5654eb2558f..134a6e39467 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -619,6 +619,21 @@ def init_numfig_format(app: Sphinx, config: Config) -> None:
     config.numfig_format = numfig_format
 
 
+def evaluate_copyright_placeholders(_app: Sphinx, config: Config) -> None:
+    """Replace copyright year placeholders (%Y) with the current year."""
+    replace_yr = str(time.localtime().tm_year)
+    for k in ('copyright', 'epub_copyright'):
+        if k in config:
+            value: str | Sequence[str] = config[k]
+            if isinstance(value, str):
+                if '%Y' in value:
+                    config[k] = value.replace('%Y', replace_yr)
+            else:
+                if any('%Y' in line for line in value):
+                    items = (line.replace('%Y', replace_yr) for line in value)
+                    config[k] = type(value)(items)  # type: ignore[call-arg]
+
+
 def correct_copyright_year(_app: Sphinx, config: Config) -> None:
     """Correct values of copyright year that are not coherent with
     the SOURCE_DATE_EPOCH environment variable (if set)
@@ -775,6 +790,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('config-inited', convert_source_suffix, priority=800)
     app.connect('config-inited', convert_highlight_options, priority=800)
     app.connect('config-inited', init_numfig_format, priority=800)
+    app.connect('config-inited', evaluate_copyright_placeholders, priority=795)
     app.connect('config-inited', correct_copyright_year, priority=800)
     app.connect('config-inited', check_confval_types, priority=800)
     app.connect('config-inited', check_primary_domain, priority=800)
diff --git a/tests/test_config/test_correct_year.py b/tests/test_config/test_copyright.py
similarity index 74%
rename from tests/test_config/test_correct_year.py
rename to tests/test_config/test_copyright.py
index 7aafe5a66f5..72cef60709b 100644
--- a/tests/test_config/test_correct_year.py
+++ b/tests/test_config/test_copyright.py
@@ -4,7 +4,11 @@
 
 import pytest
 
-from sphinx.config import Config, correct_copyright_year
+from sphinx.config import (
+    Config,
+    correct_copyright_year,
+    evaluate_copyright_placeholders,
+)
 
 LT = time.localtime()
 LT_NEW = (2009, *LT[1:], LT.tm_zone, LT.tm_gmtoff)
@@ -106,6 +110,19 @@ def test_correct_year_single_no_author(expect_date):
         assert cfg.copyright == copyright_date
 
 
+def test_correct_year_placeholder(expect_date):
+    # test that copyright is substituted
+    copyright_date = '2006-%Y, Alice'
+    cfg = Config({'copyright': copyright_date}, {})
+    assert cfg.copyright == copyright_date
+    evaluate_copyright_placeholders(None, cfg)  # type: ignore[arg-type]
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
+        assert cfg.copyright == f'2006-{expect_date}, Alice'
+    else:
+        assert cfg.copyright == '2006-2009, Alice'
+
+
 def test_correct_year_multi_line(expect_date):
     # test that copyright is substituted
     copyright_dates = (
@@ -159,6 +176,47 @@ def test_correct_year_multi_line_all_formats(expect_date):
         assert cfg.copyright == copyright_dates
 
 
+def test_correct_year_multi_line_all_formats_placeholder(expect_date):
+    # test that copyright is substituted
+    copyright_dates = (
+        '%Y',
+        '%Y Alice',
+        '%Y, Bob',
+        '2006-%Y',
+        '2006-%Y Charlie',
+        '2006-%Y, David',
+        # other format codes are left as-is
+        '2006-%y, Eve',
+        '%Y-%m-%d %H:%M:S %z, Francis',
+    )
+    cfg = Config({'copyright': copyright_dates}, {})
+    assert cfg.copyright == copyright_dates
+    evaluate_copyright_placeholders(None, cfg)  # type: ignore[arg-type]
+    correct_copyright_year(None, cfg)  # type: ignore[arg-type]
+    if expect_date and expect_date <= LOCALTIME_2009.tm_year:
+        assert cfg.copyright == (
+            f'{expect_date}',
+            f'{expect_date} Alice',
+            f'{expect_date}, Bob',
+            f'2006-{expect_date}',
+            f'2006-{expect_date} Charlie',
+            f'2006-{expect_date}, David',
+            '2006-%y, Eve',
+            '2009-%m-%d %H:%M:S %z, Francis',
+        )
+    else:
+        assert cfg.copyright == (
+            '2009',
+            '2009 Alice',
+            '2009, Bob',
+            '2006-2009',
+            '2006-2009 Charlie',
+            '2006-2009, David',
+            '2006-%y, Eve',
+            '2009-%m-%d %H:%M:S %z, Francis',
+        )
+
+
 def test_correct_year_app(expect_date, tmp_path, make_app):
     # integration test
     copyright_date = '2006-2009, Alice'

From 7ece6fc1e74242d6a35800126703e6a838b4f9b0 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 14:14:55 +0100
Subject: [PATCH 15/29] Enable automatic formatting for ``sphinx/util/``
 (#12957)

---
 .ruff.toml                 |   1 -
 sphinx/util/__init__.py    |  34 +++--
 sphinx/util/_files.py      |   8 +-
 sphinx/util/_io.py         |   3 +-
 sphinx/util/_pathlib.py    |   7 +-
 sphinx/util/_timestamps.py |   3 +-
 sphinx/util/cfamily.py     |  73 ++++++----
 sphinx/util/console.py     |   1 +
 sphinx/util/display.py     |   2 +-
 sphinx/util/docfields.py   | 168 ++++++++++++++++------
 sphinx/util/docstrings.py  |   2 +-
 sphinx/util/docutils.py    | 160 +++++++++++++++------
 sphinx/util/exceptions.py  |  16 ++-
 sphinx/util/fileutil.py    |  78 +++++++----
 sphinx/util/http_date.py   |  16 ++-
 sphinx/util/i18n.py        |  43 ++++--
 sphinx/util/images.py      |  13 +-
 sphinx/util/inspect.py     |  37 +++--
 sphinx/util/inventory.py   |  56 +++++---
 sphinx/util/logging.py     |  67 +++++----
 sphinx/util/matching.py    |   6 +-
 sphinx/util/math.py        |   2 +-
 sphinx/util/nodes.py       | 280 +++++++++++++++++++++++--------------
 sphinx/util/osutil.py      |  23 +--
 sphinx/util/parallel.py    |   7 +-
 sphinx/util/parsing.py     |   8 +-
 sphinx/util/png.py         |   6 +-
 sphinx/util/requests.py    |  12 +-
 sphinx/util/rst.py         |   8 +-
 sphinx/util/tags.py        |   7 +-
 sphinx/util/template.py    |  31 ++--
 sphinx/util/texescape.py   |   4 +-
 sphinx/util/typing.py      | 113 +++++++++------
 33 files changed, 846 insertions(+), 449 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 608c811da7c..d81928fa549 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -483,6 +483,5 @@ exclude = [
     "sphinx/search/*",
     "sphinx/testing/*",
     "sphinx/transforms/*",
-    "sphinx/util/*",
     "sphinx/writers/*",
 ]
diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py
index 6dd54cb5e76..4bb80d4a1ae 100644
--- a/sphinx/util/__init__.py
+++ b/sphinx/util/__init__.py
@@ -42,6 +42,7 @@
 
 # High-level utility functions.
 
+
 def docname_join(basedocname: str, docname: str) -> str:
     return posixpath.normpath(posixpath.join('/' + basedocname, '..', docname))[1:]
 
@@ -82,16 +83,23 @@ def __call__(self, error: UnicodeDecodeError) -> tuple[str, int]:
         if lineend == -1:
             lineend = len(error.object)
         lineno = error.object.count(b'\n', 0, error.start) + 1
-        logger.warning(__('undecodable source characters, replacing with "?": %r'),
-                       (error.object[linestart + 1:error.start] + b'>>>' +
-                        error.object[error.start:error.end] + b'<<<' +
-                        error.object[error.end:lineend]),
-                       location=(self.docname, lineno))
+        logger.warning(
+            __('undecodable source characters, replacing with "?": %r'),
+            (
+                error.object[linestart + 1 : error.start]
+                + b'>>>'
+                + error.object[error.start : error.end]
+                + b'<<<'
+                + error.object[error.end : lineend]
+            ),
+            location=(self.docname, lineno),
+        )
         return ('?', error.end)
 
 
 # Low-level utility functions and classes.
 
+
 def parselinenos(spec: str, total: int) -> list[int]:
     """Parse a line number spec (such as "1,2,4-6") and return a list of
     wanted line numbers.
@@ -136,12 +144,16 @@ def isurl(url: str) -> bool:
 
 # deprecated name -> (object to return, canonical path or empty string)
 _DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
-    'split_index_msg': (_index_entries.split_index_msg,
-                        'sphinx.util.index_entries.split_index_msg',
-                        (9, 0)),
-    'split_into': (_index_entries.split_index_msg,
-                   'sphinx.util.index_entries.split_into',
-                   (9, 0)),
+    'split_index_msg': (
+        _index_entries.split_index_msg,
+        'sphinx.util.index_entries.split_index_msg',
+        (9, 0),
+    ),
+    'split_into': (
+        _index_entries.split_index_msg,
+        'sphinx.util.index_entries.split_into',
+        (9, 0),
+    ),
     'md5': (_md5, '', (9, 0)),
     'sha1': (_sha1, '', (9, 0)),
     'import_object': (_importer.import_object, '', (10, 0)),
diff --git a/sphinx/util/_files.py b/sphinx/util/_files.py
index 9252002411f..85f63359e98 100644
--- a/sphinx/util/_files.py
+++ b/sphinx/util/_files.py
@@ -36,7 +36,9 @@ def purge_doc(self, docname: str) -> None:
                 del self[filename]
                 self._existing.discard(unique)
 
-    def merge_other(self, docnames: set[str], other: dict[str, tuple[set[str], Any]]) -> None:
+    def merge_other(
+        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+    ) -> None:
         for filename, (docs, _unique) in other.items():
             for doc in docs & set(docnames):
                 self.add_file(doc, filename)
@@ -70,7 +72,9 @@ def purge_doc(self, docname: str) -> None:
             if not docs:
                 del self[filename]
 
-    def merge_other(self, docnames: set[str], other: dict[str, tuple[set[str], Any]]) -> None:
+    def merge_other(
+        self, docnames: set[str], other: dict[str, tuple[set[str], Any]]
+    ) -> None:
         for filename, (docs, _dest) in other.items():
             for docname in docs & set(docnames):
                 self.add_file(docname, filename)
diff --git a/sphinx/util/_io.py b/sphinx/util/_io.py
index 3689d9e4511..9a36097bcf4 100644
--- a/sphinx/util/_io.py
+++ b/sphinx/util/_io.py
@@ -8,8 +8,7 @@
     from typing import Protocol
 
     class SupportsWrite(Protocol):
-        def write(self, text: str, /) -> int | None:
-            ...
+        def write(self, text: str, /) -> int | None: ...  # NoQA: E704
 
 
 class TeeStripANSI:
diff --git a/sphinx/util/_pathlib.py b/sphinx/util/_pathlib.py
index ebbb306075e..b44fec30285 100644
--- a/sphinx/util/_pathlib.py
+++ b/sphinx/util/_pathlib.py
@@ -33,9 +33,10 @@
 # https://docs.python.org/3/library/stdtypes.html#string-methods
 
 if sys.platform == 'win32':
+
     class _StrPath(WindowsPath):
         def replace(  # type: ignore[override]
-            self, old: str, new: str, count: int = -1, /,
+            self, old: str, new: str, count: int = -1, /
         ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
@@ -81,10 +82,12 @@ def __getitem__(self, item: int | slice) -> str:
         def __len__(self) -> int:
             warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
             return len(self.__str__())
+
 else:
+
     class _StrPath(PosixPath):
         def replace(  # type: ignore[override]
-            self, old: str, new: str, count: int = -1, /,
+            self, old: str, new: str, count: int = -1, /
         ) -> str:
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
diff --git a/sphinx/util/_timestamps.py b/sphinx/util/_timestamps.py
index 32aca52322a..a4836491155 100644
--- a/sphinx/util/_timestamps.py
+++ b/sphinx/util/_timestamps.py
@@ -9,4 +9,5 @@ def _format_rfc3339_microseconds(timestamp: int, /) -> str:
     :param timestamp: The timestamp to format, in microseconds.
     """
     seconds, fraction = divmod(timestamp, 10**6)
-    return time.strftime('%Y-%m-%d %H:%M:%S', time.gmtime(seconds)) + f'.{fraction // 1_000}'
+    time_tuple = time.gmtime(seconds)
+    return time.strftime('%Y-%m-%d %H:%M:%S', time_tuple) + f'.{fraction // 1_000}'
diff --git a/sphinx/util/cfamily.py b/sphinx/util/cfamily.py
index 6c85f8aad00..c12ba5ca93e 100644
--- a/sphinx/util/cfamily.py
+++ b/sphinx/util/cfamily.py
@@ -25,19 +25,23 @@
 
 _whitespace_re = re.compile(r'\s+')
 anon_identifier_re = re.compile(r'(@[a-zA-Z0-9_])[a-zA-Z0-9_]*\b')
-identifier_re = re.compile(r'''
+identifier_re = re.compile(
+    r"""
     (   # This 'extends' _anon_identifier_re with the ordinary identifiers,
         # make sure they are in sync.
         (~?\b[a-zA-Z_])  # ordinary identifiers
     |   (@[a-zA-Z0-9_])  # our extension for names of anonymous entities
     )
     [a-zA-Z0-9_]*\b
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 integer_literal_re = re.compile(r'[1-9][0-9]*(\'[0-9]+)*')
 octal_literal_re = re.compile(r'0[0-7]*(\'[0-7]+)*')
 hex_literal_re = re.compile(r'0[xX][0-9a-fA-F]+(\'[0-9a-fA-F]+)*')
 binary_literal_re = re.compile(r'0[bB][01]+(\'[01]+)*')
-integers_literal_suffix_re = re.compile(r'''
+integers_literal_suffix_re = re.compile(
+    r"""
     # unsigned and/or (long) long, in any order, but at least one of them
     (
         ([uU]    ([lL]  |  (ll)  |  (LL))?)
@@ -46,8 +50,11 @@
     )\b
     # the ending word boundary is important for distinguishing
     # between suffixes and UDLs in C++
-''', flags=re.VERBOSE)
-float_literal_re = re.compile(r'''
+""",
+    flags=re.VERBOSE,
+)
+float_literal_re = re.compile(
+    r"""
     [+-]?(
     # decimal
       ([0-9]+(\'[0-9]+)*[eE][+-]?[0-9]+(\'[0-9]+)*)
@@ -59,10 +66,13 @@
         [0-9a-fA-F]+(\'[0-9a-fA-F]+)*([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     | (0[xX][0-9a-fA-F]+(\'[0-9a-fA-F]+)*\.([pP][+-]?[0-9a-fA-F]+(\'[0-9a-fA-F]+)*)?)
     )
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 float_literal_suffix_re = re.compile(r'[fFlL]\b')
 # the ending word boundary is important for distinguishing between suffixes and UDLs in C++
-char_literal_re = re.compile(r'''
+char_literal_re = re.compile(
+    r"""
     ((?:u8)|u|U|L)?
     '(
       (?:[^\\'])
@@ -74,7 +84,9 @@
       | (?:U[0-9a-fA-F]{8})
       ))
     )'
-''', flags=re.VERBOSE)
+""",
+    flags=re.VERBOSE,
+)
 
 
 def verify_description_mode(mode: str) -> None:
@@ -116,6 +128,7 @@ def __repr__(self) -> str:
 # Attributes
 ################################################################################
 
+
 class ASTAttribute(ASTBaseBase):
     def describe_signature(self, signode: TextElement) -> None:
         raise NotImplementedError(repr(self))
@@ -134,7 +147,7 @@ def __hash__(self) -> int:
         return hash(self.arg)
 
     def _stringify(self, transform: StringifyTransform) -> str:
-        return f"[[{self.arg}]]"
+        return f'[[{self.arg}]]'
 
     def describe_signature(self, signode: TextElement) -> None:
         signode.append(addnodes.desc_sig_punctuation('[[', '[['))
@@ -258,12 +271,14 @@ def describe_signature(self, signode: TextElement) -> None:
 
 ################################################################################
 
+
 class ASTBaseParenExprList(ASTBaseBase):
     pass
 
 
 ################################################################################
 
+
 class UnsupportedMultiCharacterCharLiteral(Exception):
     pass
 
@@ -273,9 +288,13 @@ class DefinitionError(Exception):
 
 
 class BaseParser:
-    def __init__(self, definition: str, *,
-                 location: nodes.Node | tuple[str, int] | str,
-                 config: Config) -> None:
+    def __init__(
+        self,
+        definition: str,
+        *,
+        location: nodes.Node | tuple[str, int] | str,
+        config: Config,
+    ) -> None:
         self.definition = definition.strip()
         self.location = location  # for warnings
         self.config = config
@@ -315,16 +334,19 @@ def language(self) -> str:
     def status(self, msg: str) -> None:
         # for debugging
         indicator = '-' * self.pos + '^'
-        logger.debug(f"{msg}\n{self.definition}\n{indicator}")  # NoQA: G004
+        logger.debug(f'{msg}\n{self.definition}\n{indicator}')  # NoQA: G004
 
     def fail(self, msg: str) -> None:
         errors = []
         indicator = '-' * self.pos + '^'
-        exMain = DefinitionError(
-            'Invalid %s declaration: %s [error at %d]\n  %s\n  %s' %
-            (self.language, msg, self.pos, self.definition, indicator))
-        errors.append((exMain, "Main error"))
-        errors.extend((err, "Potential other error") for err in self.otherErrors)
+        msg = (
+            f'Invalid {self.language} declaration: {msg} [error at {self.pos}]\n'
+            f'  {self.definition}\n'
+            f'  {indicator}'
+        )
+        exc_main = DefinitionError(msg)
+        errors.append((exc_main, 'Main error'))
+        errors.extend((err, 'Potential other error') for err in self.otherErrors)
         self.otherErrors = []
         raise self._make_multi_error(errors, '')
 
@@ -342,7 +364,7 @@ def match(self, regex: re.Pattern[str]) -> bool:
 
     def skip_string(self, string: str) -> bool:
         strlen = len(string)
-        if self.definition[self.pos:self.pos + strlen] == string:
+        if self.definition[self.pos : self.pos + strlen] == string:
             self.pos += strlen
             return True
         return False
@@ -383,14 +405,14 @@ def matched_text(self) -> str:
         return ''
 
     def read_rest(self) -> str:
-        rv = self.definition[self.pos:]
+        rv = self.definition[self.pos :]
         self.pos = self.end
         return rv
 
     def assert_end(self, *, allowSemicolon: bool = False) -> None:
         self.skip_ws()
         if allowSemicolon:
-            if not self.eof and self.definition[self.pos:] != ';':
+            if not self.eof and self.definition[self.pos :] != ';':
                 self.fail('Expected end of definition or ;.')
         else:
             if not self.eof:
@@ -418,13 +440,14 @@ def _parse_balanced_token_seq(self, end: list[str]) -> str:
                 symbols.append(brackets[self.current_char])
             elif len(symbols) > 0 and self.current_char == symbols[-1]:
                 symbols.pop()
-            elif self.current_char in ")]}":
+            elif self.current_char in ')]}':
                 self.fail("Unexpected '%s' in balanced-token-seq." % self.current_char)
             self.pos += 1
         if self.eof:
-            self.fail("Could not find end of balanced-token-seq starting at %d."
-                      % startPos)
-        return self.definition[startPos:self.pos]
+            self.fail(
+                f'Could not find end of balanced-token-seq starting at {startPos}.'
+            )
+        return self.definition[startPos : self.pos]
 
     def _parse_attribute(self) -> ASTAttribute | None:
         self.skip_ws()
diff --git a/sphinx/util/console.py b/sphinx/util/console.py
index 2b24715ca22..9a5a15a5bd9 100644
--- a/sphinx/util/console.py
+++ b/sphinx/util/console.py
@@ -41,6 +41,7 @@ def turquoise(text: str) -> str: ...  # NoQA: E704
 try:
     # check if colorama is installed to support color on Windows
     import colorama
+
     COLORAMA_AVAILABLE = True
 except ImportError:
     COLORAMA_AVAILABLE = False
diff --git a/sphinx/util/display.py b/sphinx/util/display.py
index f3aea633e34..eebbb1a5133 100644
--- a/sphinx/util/display.py
+++ b/sphinx/util/display.py
@@ -78,7 +78,7 @@ def __exit__(
         val: BaseException | None,
         tb: TracebackType | None,
     ) -> bool:
-        prefix = "" if self.nonl else bold(self.message + ': ')
+        prefix = '' if self.nonl else bold(self.message + ': ')
         if isinstance(val, SkipProgressMessage):
             logger.info(prefix + __('skipped'))
             if val.args:
diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py
index 1c32ff3fce1..bb8142570f0 100644
--- a/sphinx/util/docfields.py
+++ b/sphinx/util/docfields.py
@@ -3,6 +3,7 @@
 "Doc fields" are reST field lists in object descriptions that will
 be domain-specifically transformed to a more appealing presentation.
 """
+
 from __future__ import annotations
 
 import contextlib
@@ -70,10 +71,17 @@ def __init__(
         self.rolename = rolename
         self.bodyrolename = bodyrolename
 
-    def make_xref(self, rolename: str, domain: str, target: str,
-                  innernode: type[TextlikeNode] = addnodes.literal_emphasis,
-                  contnode: Node | None = None, env: BuildEnvironment | None = None,
-                  inliner: Inliner | None = None, location: Element | None = None) -> Node:
+    def make_xref(
+        self,
+        rolename: str,
+        domain: str,
+        target: str,
+        innernode: type[TextlikeNode] = addnodes.literal_emphasis,
+        contnode: Node | None = None,
+        env: BuildEnvironment | None = None,
+        inliner: Inliner | None = None,
+        location: Element | None = None,
+    ) -> Node:
         # note: for backwards compatibility env is last, but not optional
         assert env is not None
         assert (inliner is None) == (location is None), (inliner, location)
@@ -84,11 +92,18 @@ def make_xref(self, rolename: str, domain: str, target: str,
         role = env.get_domain(domain).role(rolename)
         if role is None or inliner is None:
             if role is None and inliner is not None:
-                msg = __("Problem in %s domain: field is supposed "
-                         "to use role '%s', but that role is not in the domain.")
+                msg = __(
+                    'Problem in %s domain: field is supposed '
+                    "to use role '%s', but that role is not in the domain."
+                )
                 logger.warning(__(msg), domain, rolename, location=location)
-            refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
-                                            reftype=rolename, reftarget=target)
+            refnode = addnodes.pending_xref(
+                '',
+                refdomain=domain,
+                refexplicit=False,
+                reftype=rolename,
+                reftarget=target,
+            )
             refnode += contnode or innernode(target, target)  # type: ignore[call-arg]
             env.get_domain(domain).process_field_xref(refnode)
             return refnode
@@ -99,13 +114,22 @@ def make_xref(self, rolename: str, domain: str, target: str,
         ns, messages = role(rolename, target, target, lineno, inliner, {}, [])
         return nodes.inline(target, '', *ns)
 
-    def make_xrefs(self, rolename: str, domain: str, target: str,
-                   innernode: type[TextlikeNode] = addnodes.literal_emphasis,
-                   contnode: Node | None = None, env: BuildEnvironment | None = None,
-                   inliner: Inliner | None = None, location: Element | None = None,
-                   ) -> list[Node]:
-        return [self.make_xref(rolename, domain, target, innernode, contnode,
-                               env, inliner, location)]
+    def make_xrefs(
+        self,
+        rolename: str,
+        domain: str,
+        target: str,
+        innernode: type[TextlikeNode] = addnodes.literal_emphasis,
+        contnode: Node | None = None,
+        env: BuildEnvironment | None = None,
+        inliner: Inliner | None = None,
+        location: Element | None = None,
+    ) -> list[Node]:
+        return [
+            self.make_xref(
+                rolename, domain, target, innernode, contnode, env, inliner, location
+            )
+        ]
 
     def make_entry(self, fieldarg: str, content: list[Node]) -> tuple[str, list[Node]]:
         return (fieldarg, content)
@@ -123,17 +147,35 @@ def make_field(
         fieldname = nodes.field_name('', self.label)
         if fieldarg:
             fieldname += nodes.Text(' ')
-            fieldname.extend(self.make_xrefs(self.rolename, domain,
-                                             fieldarg, nodes.Text,
-                                             env=env, inliner=inliner, location=location))
+            fieldname.extend(
+                self.make_xrefs(
+                    self.rolename,
+                    domain,
+                    fieldarg,
+                    nodes.Text,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
+            )
 
         if len(content) == 1 and (
-                isinstance(content[0], nodes.Text) or
-                (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and
-                 isinstance(content[0][0], nodes.Text))):
-            content = self.make_xrefs(self.bodyrolename, domain,
-                                      content[0].astext(), contnode=content[0],
-                                      env=env, inliner=inliner, location=location)
+            isinstance(content[0], nodes.Text)
+            or (
+                isinstance(content[0], nodes.inline)
+                and len(content[0]) == 1
+                and isinstance(content[0][0], nodes.Text)
+            )
+        ):
+            content = self.make_xrefs(
+                self.bodyrolename,
+                domain,
+                content[0].astext(),
+                contnode=content[0],
+                env=env,
+                inliner=inliner,
+                location=location,
+            )
         fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
         return nodes.field('', fieldname, fieldbody)
 
@@ -155,8 +197,14 @@ class GroupedField(Field):
     is_grouped = True
     list_type = nodes.bullet_list
 
-    def __init__(self, name: str, names: tuple[str, ...] = (), label: str = '',
-                 rolename: str = '', can_collapse: bool = False) -> None:
+    def __init__(
+        self,
+        name: str,
+        names: tuple[str, ...] = (),
+        label: str = '',
+        rolename: str = '',
+        can_collapse: bool = False,
+    ) -> None:
         super().__init__(name, names, label, True, rolename)
         self.can_collapse = can_collapse
 
@@ -173,9 +221,17 @@ def make_field(
         listnode = self.list_type()
         for fieldarg, content in items:
             par = nodes.paragraph()
-            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
-                                       addnodes.literal_strong,
-                                       env=env, inliner=inliner, location=location))
+            par.extend(
+                self.make_xrefs(
+                    self.rolename,
+                    domain,
+                    fieldarg,
+                    addnodes.literal_strong,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
+            )
             par += nodes.Text(' -- ')
             par += content
             listnode += nodes.list_item('', par)
@@ -236,8 +292,11 @@ def make_field(
     ) -> nodes.field:
         def handle_item(fieldarg: str, content: list[Node]) -> nodes.paragraph:
             par = nodes.paragraph()
-            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
-                                       addnodes.literal_strong, env=env))
+            par.extend(
+                self.make_xrefs(
+                    self.rolename, domain, fieldarg, addnodes.literal_strong, env=env
+                )
+            )
             if fieldarg in types:
                 par += nodes.Text(' (')
                 # NOTE: using .pop() here to prevent a single type node to be
@@ -246,9 +305,17 @@ def handle_item(fieldarg: str, content: list[Node]) -> nodes.paragraph:
                 fieldtype = types.pop(fieldarg)
                 if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                     typename = fieldtype[0].astext()
-                    par.extend(self.make_xrefs(self.typerolename, domain, typename,
-                                               addnodes.literal_emphasis, env=env,
-                                               inliner=inliner, location=location))
+                    par.extend(
+                        self.make_xrefs(
+                            self.typerolename,
+                            domain,
+                            typename,
+                            addnodes.literal_emphasis,
+                            env=env,
+                            inliner=inliner,
+                            location=location,
+                        )
+                    )
                 else:
                     par += fieldtype
                 par += nodes.Text(')')
@@ -329,8 +396,13 @@ def transform(self, node: nodes.field_list) -> None:
                 entries.append(field)
 
                 # but if this has a type then we can at least link it
-                if (typedesc and is_typefield and content and
-                        len(content) == 1 and isinstance(content[0], nodes.Text)):
+                if (
+                    typedesc
+                    and is_typefield
+                    and content
+                    and len(content) == 1
+                    and isinstance(content[0], nodes.Text)
+                ):
                     typed_field = cast(TypedField, typedesc)
                     target = content[0].astext()
                     xrefs = typed_field.make_xrefs(
@@ -356,7 +428,9 @@ def transform(self, node: nodes.field_list) -> None:
             if is_typefield:
                 # filter out only inline nodes; others will result in invalid
                 # markup being written out
-                content = [n for n in content if isinstance(n, nodes.Inline | nodes.Text)]
+                content = [
+                    n for n in content if isinstance(n, nodes.Inline | nodes.Text)
+                ]
                 if content:
                     types.setdefault(typename, {})[fieldarg] = content
                 continue
@@ -368,12 +442,10 @@ def transform(self, node: nodes.field_list) -> None:
                 except ValueError:
                     pass
                 else:
-                    types.setdefault(typename, {})[argname] = \
-                        [nodes.Text(argtype)]
+                    types.setdefault(typename, {})[argname] = [nodes.Text(argtype)]
                     fieldarg = argname
 
-            translatable_content = nodes.inline(field_body.rawsource,
-                                                translatable=True)
+            translatable_content = nodes.inline(field_body.rawsource, translatable=True)
             translatable_content.document = field_body.parent.document
             translatable_content.source = field_body.parent.source
             translatable_content.line = field_body.parent.line
@@ -383,7 +455,9 @@ def transform(self, node: nodes.field_list) -> None:
             # get one entry per field
             if typedesc.is_grouped:
                 if typename in groupindices:
-                    group = cast(tuple[Field, list, Node], entries[groupindices[typename]])
+                    group = cast(
+                        tuple[Field, list, Node], entries[groupindices[typename]]
+                    )
                 else:
                     groupindices[typename] = len(entries)
                     group = (typedesc, [], field)
@@ -406,7 +480,13 @@ def transform(self, node: nodes.field_list) -> None:
                 env = self.directive.state.document.settings.env
                 inliner = self.directive.state.inliner
                 domain = self.directive.domain or ''
-                new_list += fieldtype.make_field(fieldtypes, domain, items,
-                                                 env=env, inliner=inliner, location=location)
+                new_list += fieldtype.make_field(
+                    fieldtypes,
+                    domain,
+                    items,
+                    env=env,
+                    inliner=inliner,
+                    location=location,
+                )
 
         node.replace_self(new_list)
diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py
index 6ccc5389b9b..87123768054 100644
--- a/sphinx/util/docstrings.py
+++ b/sphinx/util/docstrings.py
@@ -29,7 +29,7 @@ def separate_metadata(s: str | None) -> tuple[str | None, dict[str, str]]:
                 field_name = matched.group()[1:].split(':', 1)[0]
                 if field_name.startswith('meta '):
                     name = field_name[5:].strip()
-                    metadata[name] = line[matched.end():].strip()
+                    metadata[name] = line[matched.end() :].strip()
                 else:
                     lines.append(line)
             else:
diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py
index 7ee8a82dffa..3a74040792e 100644
--- a/sphinx/util/docutils.py
+++ b/sphinx/util/docutils.py
@@ -24,7 +24,9 @@
 from sphinx.util.parsing import nested_parse_to_nodes
 
 logger = logging.getLogger(__name__)
-report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) ')
+report_re = re.compile(
+    '^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\\d+)?\\) '
+)
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator  # NoQA: TCH003
@@ -114,8 +116,8 @@ def unregister_node(node: type[Element]) -> None:
     This is inverse of ``nodes._add_nodes_class_names()``.
     """
     if hasattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__):
-        delattr(nodes.GenericNodeVisitor, "visit_" + node.__name__)
-        delattr(nodes.GenericNodeVisitor, "depart_" + node.__name__)
+        delattr(nodes.GenericNodeVisitor, 'visit_' + node.__name__)
+        delattr(nodes.GenericNodeVisitor, 'depart_' + node.__name__)
         delattr(nodes.SparseNodeVisitor, 'visit_' + node.__name__)
         delattr(nodes.SparseNodeVisitor, 'depart_' + node.__name__)
 
@@ -129,7 +131,9 @@ def patched_get_language() -> Iterator[None]:
     """
     from docutils.languages import get_language
 
-    def patched_get_language(language_code: str, reporter: Reporter | None = None) -> Any:
+    def patched_get_language(
+        language_code: str, reporter: Reporter | None = None
+    ) -> Any:
         return get_language(language_code)
 
     try:
@@ -153,7 +157,9 @@ def patched_rst_get_language() -> Iterator[None]:
     """
     from docutils.parsers.rst.languages import get_language
 
-    def patched_get_language(language_code: str, reporter: Reporter | None = None) -> Any:
+    def patched_get_language(
+        language_code: str, reporter: Reporter | None = None
+    ) -> Any:
         return get_language(language_code)
 
     try:
@@ -170,7 +176,9 @@ def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
     try:
         docutilsconfig = os.environ.get('DOCUTILSCONFIG', None)
         if confdir:
-            os.environ['DOCUTILSCONFIG'] = path.join(path.abspath(confdir), 'docutils.conf')
+            os.environ['DOCUTILSCONFIG'] = path.join(
+                path.abspath(confdir), 'docutils.conf'
+            )
 
         yield
     finally:
@@ -183,9 +191,11 @@ def using_user_docutils_conf(confdir: str | None) -> Iterator[None]:
 @contextmanager
 def patch_docutils(confdir: str | None = None) -> Iterator[None]:
     """Patch to docutils temporarily."""
-    with patched_get_language(), \
-         patched_rst_get_language(), \
-         using_user_docutils_conf(confdir):
+    with (
+        patched_get_language(),
+        patched_rst_get_language(),
+        using_user_docutils_conf(confdir),
+    ):
         yield
 
 
@@ -204,7 +214,7 @@ def __enter__(self) -> None:
         self.enable()
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any,
+        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
     ) -> None:
         self.disable()
 
@@ -219,16 +229,27 @@ def disable(self) -> None:
         directives.directive = self.directive_func
         roles.role = self.role_func
 
-    def directive(self,
-                  directive_name: str, language_module: ModuleType, document: nodes.document,
-                  ) -> tuple[type[Directive] | None, list[system_message]]:
+    def directive(
+        self,
+        directive_name: str,
+        language_module: ModuleType,
+        document: nodes.document,
+    ) -> tuple[type[Directive] | None, list[system_message]]:
         return self.directive_func(directive_name, language_module, document)
 
     def role(
-        self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter,
+        self,
+        role_name: str,
+        language_module: ModuleType,
+        lineno: int,
+        reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
-        return self.role_func(role_name, language_module,  # type: ignore[return-value]
-                              lineno, reporter)
+        return self.role_func(
+            role_name,
+            language_module,  # type: ignore[return-value]
+            lineno,
+            reporter,
+        )
 
 
 class ElementLookupError(Exception):
@@ -258,7 +279,9 @@ def lookup_domain_element(self, type: str, name: str) -> Any:
                 if element is not None:
                     return element, []
             else:
-                logger.warning(_('unknown directive or role name: %s:%s'), domain_name, name)
+                logger.warning(
+                    _('unknown directive or role name: %s:%s'), domain_name, name
+                )
         # else look in the default domain
         else:
             def_domain = self.env.temp_data.get('default_domain')
@@ -274,16 +297,23 @@ def lookup_domain_element(self, type: str, name: str) -> Any:
 
         raise ElementLookupError
 
-    def directive(self,
-                  directive_name: str, language_module: ModuleType, document: nodes.document,
-                  ) -> tuple[type[Directive] | None, list[system_message]]:
+    def directive(
+        self,
+        directive_name: str,
+        language_module: ModuleType,
+        document: nodes.document,
+    ) -> tuple[type[Directive] | None, list[system_message]]:
         try:
             return self.lookup_domain_element('directive', directive_name)
         except ElementLookupError:
             return super().directive(directive_name, language_module, document)
 
     def role(
-        self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter,
+        self,
+        role_name: str,
+        language_module: ModuleType,
+        lineno: int,
+        reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
         try:
             return self.lookup_domain_element('role', role_name)
@@ -295,26 +325,39 @@ class WarningStream:
     def write(self, text: str) -> None:
         matched = report_re.search(text)
         if not matched:
-            logger.warning(text.rstrip("\r\n"), type="docutils")
+            logger.warning(text.rstrip('\r\n'), type='docutils')
         else:
             location, type, level = matched.groups()
             message = report_re.sub('', text).rstrip()
-            logger.log(type, message, location=location, type="docutils")
+            logger.log(type, message, location=location, type='docutils')
 
 
 class LoggingReporter(Reporter):
     @classmethod
-    def from_reporter(cls: type[LoggingReporter], reporter: Reporter) -> LoggingReporter:
+    def from_reporter(
+        cls: type[LoggingReporter], reporter: Reporter
+    ) -> LoggingReporter:
         """Create an instance of LoggingReporter from other reporter object."""
-        return cls(reporter.source, reporter.report_level, reporter.halt_level,
-                   reporter.debug_flag, reporter.error_handler)
+        return cls(
+            reporter.source,
+            reporter.report_level,
+            reporter.halt_level,
+            reporter.debug_flag,
+            reporter.error_handler,
+        )
 
-    def __init__(self, source: str, report_level: int = Reporter.WARNING_LEVEL,
-                 halt_level: int = Reporter.SEVERE_LEVEL, debug: bool = False,
-                 error_handler: str = 'backslashreplace') -> None:
+    def __init__(
+        self,
+        source: str,
+        report_level: int = Reporter.WARNING_LEVEL,
+        halt_level: int = Reporter.SEVERE_LEVEL,
+        debug: bool = False,
+        error_handler: str = 'backslashreplace',
+    ) -> None:
         stream = cast(IO, WarningStream())
-        super().__init__(source, report_level, halt_level,
-                         stream, debug, error_handler=error_handler)
+        super().__init__(
+            source, report_level, halt_level, stream, debug, error_handler=error_handler
+        )
 
 
 class NullReporter(Reporter):
@@ -351,8 +394,13 @@ def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
 
     def write(self, data: str) -> str:
-        if (self.destination_path and self.autoclose and 'b' not in self.mode and
-                self.overwrite_if_changed and os.path.exists(self.destination_path)):
+        if (
+            self.destination_path
+            and self.autoclose
+            and 'b' not in self.mode
+            and self.overwrite_if_changed
+            and os.path.exists(self.destination_path)
+        ):
             with open(self.destination_path, encoding=self.encoding) as f:
                 # skip writing: content not changed
                 if f.read() == data:
@@ -416,7 +464,9 @@ def get_location(self) -> str:
             return f'<unknown>:{line}'
         return ''
 
-    def parse_content_to_nodes(self, allow_section_headings: bool = False) -> list[Node]:
+    def parse_content_to_nodes(
+        self, allow_section_headings: bool = False
+    ) -> list[Node]:
         """Parse the directive's content into nodes.
 
         :param allow_section_headings:
@@ -437,7 +487,12 @@ def parse_content_to_nodes(self, allow_section_headings: bool = False) -> list[N
         )
 
     def parse_text_to_nodes(
-        self, text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False,
+        self,
+        text: str = '',
+        /,
+        *,
+        offset: int = -1,
+        allow_section_headings: bool = False,
     ) -> list[Node]:
         """Parse *text* into nodes.
 
@@ -465,7 +520,7 @@ def parse_text_to_nodes(
         )
 
     def parse_inline(
-        self, text: str, *, lineno: int = -1,
+        self, text: str, *, lineno: int = -1
     ) -> tuple[list[Node], list[system_message]]:
         """Parse *text* as inline elements.
 
@@ -496,6 +551,7 @@ class SphinxRole:
               This class is strongly coupled with Sphinx.
     """
 
+    # fmt: off
     name: str         #: The role name actually used in the document.
     rawtext: str      #: A string containing the entire interpreted text input.
     text: str         #: The interpreted text content.
@@ -507,10 +563,18 @@ class SphinxRole:
     #: A list of strings, the directive content for customisation
     #: (from the "role" directive).
     content: Sequence[str]
-
-    def __call__(self, name: str, rawtext: str, text: str, lineno: int,
-                 inliner: Inliner, options: dict | None = None, content: Sequence[str] = (),
-                 ) -> tuple[list[Node], list[system_message]]:
+    # fmt: on
+
+    def __call__(
+        self,
+        name: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: dict | None = None,
+        content: Sequence[str] = (),
+    ) -> tuple[list[Node], list[system_message]]:
         self.rawtext = rawtext
         self.text = unescape(text)
         self.lineno = lineno
@@ -585,17 +649,26 @@ class ReferenceRole(SphinxRole):
     .. versionadded:: 2.0
     """
 
+    # fmt: off
     has_explicit_title: bool    #: A boolean indicates the role has explicit title or not.
     disabled: bool              #: A boolean indicates the reference is disabled.
     title: str                  #: The link title for the interpreted text.
     target: str                 #: The link target for the interpreted text.
+    # fmt: on
 
     # \x00 means the "<" was backslash-escaped
     explicit_title_re = re.compile(r'^(.+?)\s*(?<!\x00)<(.*?)>$', re.DOTALL)
 
-    def __call__(self, name: str, rawtext: str, text: str, lineno: int,
-                 inliner: Inliner, options: dict | None = None, content: Sequence[str] = (),
-                 ) -> tuple[list[Node], list[system_message]]:
+    def __call__(
+        self,
+        name: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: dict | None = None,
+        content: Sequence[str] = (),
+    ) -> tuple[list[Node], list[system_message]]:
         if options is None:
             options = {}
 
@@ -698,6 +771,7 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
 
     # Create a new instance of nodes.document using cached reporter
     from sphinx import addnodes
+
     document = addnodes.document(settings, reporter, source=source_path)
     document.note_source(source_path, -1)
     return document
diff --git a/sphinx/util/exceptions.py b/sphinx/util/exceptions.py
index 577ec734e59..a0403c384d9 100644
--- a/sphinx/util/exceptions.py
+++ b/sphinx/util/exceptions.py
@@ -31,12 +31,18 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
         last_msgs = exts_list = ''
     else:
         extensions = app.extensions.values()
-        last_msgs = '\n'.join(f'#   {strip_escape_sequences(s).strip()}'
-                              for s in app.messagelog)
-        exts_list = '\n'.join(f'#   {ext.name} ({ext.version})' for ext in extensions
-                              if ext.version != 'builtin')
+        last_msgs = '\n'.join(
+            f'#   {strip_escape_sequences(s).strip()}' for s in app.messagelog
+        )
+        exts_list = '\n'.join(
+            f'#   {ext.name} ({ext.version})'
+            for ext in extensions
+            if ext.version != 'builtin'
+        )
 
-    with NamedTemporaryFile('w', suffix='.log', prefix='sphinx-err-', delete=False) as f:
+    with NamedTemporaryFile(
+        'w', suffix='.log', prefix='sphinx-err-', delete=False
+    ) as f:
         f.write(f"""\
 # Platform:         {sys.platform}; ({platform.platform()})
 # Sphinx version:   {sphinx.__display_version__}
diff --git a/sphinx/util/fileutil.py b/sphinx/util/fileutil.py
index 62b72f017fd..acd52b07674 100644
--- a/sphinx/util/fileutil.py
+++ b/sphinx/util/fileutil.py
@@ -35,11 +35,14 @@ def _template_basename(filename: str | os.PathLike[str]) -> str | None:
     return None
 
 
-def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLike[str],
-                    context: dict[str, Any] | None = None,
-                    renderer: BaseRenderer | None = None,
-                    *,
-                    force: bool = False) -> None:
+def copy_asset_file(
+    source: str | os.PathLike[str],
+    destination: str | os.PathLike[str],
+    context: dict[str, Any] | None = None,
+    renderer: BaseRenderer | None = None,
+    *,
+    force: bool = False,
+) -> None:
     """Copy an asset file to destination.
 
     On copying, it expands the template variables if context argument is given and
@@ -62,38 +65,51 @@ def copy_asset_file(source: str | os.PathLike[str], destination: str | os.PathLi
     if _template_basename(source) and context is not None:
         if renderer is None:
             from sphinx.util.template import SphinxRenderer
+
             renderer = SphinxRenderer()
 
         with open(source, encoding='utf-8') as fsrc:
             template_content = fsrc.read()
         rendered_template = renderer.render_string(template_content, context)
 
-        if (
-            not force
-            and destination.exists()
-            and template_content != rendered_template
-        ):
-            msg = __('Aborted attempted copy from rendered template %s to %s '
-                     '(the destination path has existing data).')
-            logger.warning(msg, os.fsdecode(source), os.fsdecode(destination),
-                           type='misc', subtype='copy_overwrite')
+        if not force and destination.exists() and template_content != rendered_template:
+            msg = __(
+                'Aborted attempted copy from rendered template %s to %s '
+                '(the destination path has existing data).'
+            )
+            logger.warning(
+                msg,
+                os.fsdecode(source),
+                os.fsdecode(destination),
+                type='misc',
+                subtype='copy_overwrite',
+            )
             return
 
         destination = _template_basename(destination) or destination
         with open(destination, 'w', encoding='utf-8') as fdst:
             msg = __('Writing evaluated template result to %s')
-            logger.info(msg, os.fsdecode(destination), type='misc',
-                        subtype='template_evaluation')
+            logger.info(
+                msg,
+                os.fsdecode(destination),
+                type='misc',
+                subtype='template_evaluation',
+            )
             fdst.write(rendered_template)
     else:
         copyfile(source, destination, force=force)
 
 
-def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[str],
-               excluded: PathMatcher = lambda path: False,
-               context: dict[str, Any] | None = None, renderer: BaseRenderer | None = None,
-               onerror: Callable[[str, Exception], None] | None = None,
-               *, force: bool = False) -> None:
+def copy_asset(
+    source: str | os.PathLike[str],
+    destination: str | os.PathLike[str],
+    excluded: PathMatcher = lambda path: False,
+    context: dict[str, Any] | None = None,
+    renderer: BaseRenderer | None = None,
+    onerror: Callable[[str, Exception], None] | None = None,
+    *,
+    force: bool = False,
+) -> None:
     """Copy asset files to destination recursively.
 
     On copying, it expands the template variables if context argument is given and
@@ -114,14 +130,14 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
 
     if renderer is None:
         from sphinx.util.template import SphinxRenderer
+
         renderer = SphinxRenderer()
 
     ensuredir(destination)
     if os.path.isfile(source):
-        copy_asset_file(source, destination,
-                        context=context,
-                        renderer=renderer,
-                        force=force)
+        copy_asset_file(
+            source, destination, context=context, renderer=renderer, force=force
+        )
         return
 
     for root, dirs, files in os.walk(source, followlinks=True):
@@ -135,11 +151,13 @@ def copy_asset(source: str | os.PathLike[str], destination: str | os.PathLike[st
         for filename in files:
             if not excluded(posixpath.join(reldir, filename)):
                 try:
-                    copy_asset_file(posixpath.join(root, filename),
-                                    posixpath.join(destination, reldir),
-                                    context=context,
-                                    renderer=renderer,
-                                    force=force)
+                    copy_asset_file(
+                        posixpath.join(root, filename),
+                        posixpath.join(destination, reldir),
+                        context=context,
+                        renderer=renderer,
+                        force=force,
+                    )
                 except Exception as exc:
                     if onerror:
                         onerror(posixpath.join(root, filename), exc)
diff --git a/sphinx/util/http_date.py b/sphinx/util/http_date.py
index 4908101bcfb..d8c51ae9b58 100644
--- a/sphinx/util/http_date.py
+++ b/sphinx/util/http_date.py
@@ -12,7 +12,7 @@
 _WEEKDAY_NAME = ('Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun')
 _MONTH_NAME = ('',  # Placeholder for indexing purposes
                'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
-               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')
+               'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')  # fmt: skip
 _GMT_OFFSET = float(time.localtime().tm_gmtoff)
 
 
@@ -29,18 +29,20 @@ def rfc1123_to_epoch(rfc1123: str) -> float:
     t = parsedate_tz(rfc1123)
     if t is None:
         raise ValueError
-    if not rfc1123.endswith(" GMT"):
+    if not rfc1123.endswith(' GMT'):
         warnings.warn(
-            "HTTP-date string does not meet RFC 7231 requirements "
+            'HTTP-date string does not meet RFC 7231 requirements '
             f"(must end with 'GMT'): {rfc1123!r}",
-            RemovedInSphinx90Warning, stacklevel=3,
+            RemovedInSphinx90Warning,
+            stacklevel=3,
         )
     epoch_secs = time.mktime(time.struct_time(t[:9])) + _GMT_OFFSET
     if (gmt_offset := t[9]) != 0:
         warnings.warn(
-            "HTTP-date string does not meet RFC 7231 requirements "
-            f"(must be GMT time): {rfc1123!r}",
-            RemovedInSphinx90Warning, stacklevel=3,
+            'HTTP-date string does not meet RFC 7231 requirements '
+            f'(must be GMT time): {rfc1123!r}',
+            RemovedInSphinx90Warning,
+            stacklevel=3,
         )
         return epoch_secs - (gmt_offset or 0)
     return epoch_secs
diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py
index e788b7ab376..5fca3c811b5 100644
--- a/sphinx/util/i18n.py
+++ b/sphinx/util/i18n.py
@@ -75,7 +75,6 @@ class LocaleFileInfoBase(NamedTuple):
 
 
 class CatalogInfo(LocaleFileInfoBase):
-
     @property
     def po_file(self) -> str:
         return self.domain + '.po'
@@ -94,8 +93,9 @@ def mo_path(self) -> str:
 
     def is_outdated(self) -> bool:
         return (
-            not path.exists(self.mo_path) or
-            _last_modified_time(self.mo_path) < _last_modified_time(self.po_path))
+            not path.exists(self.mo_path)
+            or _last_modified_time(self.mo_path) < _last_modified_time(self.po_path)
+        )  # fmt: skip
 
     def write_mo(self, locale: str, use_fuzzy: bool = False) -> None:
         with open(self.po_path, encoding=self.charset) as file_po:
@@ -115,8 +115,13 @@ def write_mo(self, locale: str, use_fuzzy: bool = False) -> None:
 class CatalogRepository:
     """A repository for message catalogs."""
 
-    def __init__(self, basedir: str | os.PathLike[str], locale_dirs: list[str],
-                 language: str, encoding: str) -> None:
+    def __init__(
+        self,
+        basedir: str | os.PathLike[str],
+        locale_dirs: list[str],
+        language: str,
+        encoding: str,
+    ) -> None:
         self.basedir = basedir
         self._locale_dirs = locale_dirs
         self.language = language
@@ -205,13 +210,17 @@ def docname_to_domain(docname: str, compaction: bool | str) -> str:
     '%z':  'ZZZ',     # UTC offset in the form ±HHMM[SS[.ffffff]]
                       # (empty string if the object is naive).
     '%%':  '%',
-}
+}  # fmt: skip
 
 date_format_re = re.compile('(%s)' % '|'.join(date_format_mappings))
 
 
-def babel_format_date(date: datetime, format: str, locale: str,
-                      formatter: Formatter = babel.dates.format_date) -> str:
+def babel_format_date(
+    date: datetime,
+    format: str,
+    locale: str,
+    formatter: Formatter = babel.dates.format_date,
+) -> str:
     # Check if we have the tzinfo attribute. If not we cannot do any time
     # related formats.
     if not hasattr(date, 'tzinfo'):
@@ -223,8 +232,13 @@ def babel_format_date(date: datetime, format: str, locale: str,
         # fallback to English
         return formatter(date, format, locale='en')
     except AttributeError:
-        logger.warning(__('Invalid date format. Quote the string by single quote '
-                          'if you want to output it directly: %s'), format)
+        logger.warning(
+            __(
+                'Invalid date format. Quote the string by single quote '
+                'if you want to output it directly: %s'
+            ),
+            format,
+        )
         return format
 
 
@@ -267,12 +281,15 @@ def format_date(
             else:
                 function = babel.dates.format_datetime
 
-            result.append(babel_format_date(date, babel_format, locale=language,
-                                            formatter=function))
+            result.append(
+                babel_format_date(
+                    date, babel_format, locale=language, formatter=function
+                )
+            )
         else:
             result.append(token)
 
-    return "".join(result)
+    return ''.join(result)
 
 
 def get_image_filename_for_language(
diff --git a/sphinx/util/images.py b/sphinx/util/images.py
index 70735c6cfba..4a6a58698e4 100644
--- a/sphinx/util/images.py
+++ b/sphinx/util/images.py
@@ -13,6 +13,7 @@
 
 try:
     from PIL import Image
+
     PILLOW_AVAILABLE = True
 except ImportError:
     PILLOW_AVAILABLE = False
@@ -54,13 +55,13 @@ def get_image_size(filename: str) -> tuple[int, int] | None:
 
 
 @overload
-def guess_mimetype(filename: PathLike[str] | str, default: str) -> str:
-    ...
+def guess_mimetype(filename: PathLike[str] | str, default: str) -> str: ...  # NoQA: E704
 
 
 @overload
-def guess_mimetype(filename: PathLike[str] | str, default: None = None) -> str | None:
-    ...
+def guess_mimetype(  # NoQA: E704
+    filename: PathLike[str] | str, default: None = None
+) -> str | None: ...
 
 
 def guess_mimetype(
@@ -121,12 +122,12 @@ def _image_type_from_file(filename: PathLike[str] | str) -> str:
 
     # JPEG data
     # https://en.wikipedia.org/wiki/JPEG_File_Interchange_Format#File_format_structure
-    if header.startswith(b'\xFF\xD8'):
+    if header.startswith(b'\xff\xd8'):
         return 'jpeg'
 
     # Portable Network Graphics
     # https://en.wikipedia.org/wiki/PNG#File_header
-    if header.startswith(b'\x89PNG\r\n\x1A\n'):
+    if header.startswith(b'\x89PNG\r\n\x1a\n'):
         return 'png'
 
     # Scalable Vector Graphics
diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py
index 096da877c11..33340bb7182 100644
--- a/sphinx/util/inspect.py
+++ b/sphinx/util/inspect.py
@@ -52,11 +52,7 @@ def __delete__(self, __instance: Any) -> None: ...  # NoQA: E704
         | types.MethodDescriptorType
         | types.ClassMethodDescriptorType
     )
-    _SignatureType: TypeAlias = (
-        Callable[..., Any]
-        | staticmethod
-        | classmethod
-    )
+    _SignatureType: TypeAlias = Callable[..., Any] | staticmethod | classmethod
 
 logger = logging.getLogger(__name__)
 
@@ -266,7 +262,8 @@ def isstaticmethod(
 def isdescriptor(x: Any) -> TypeIs[_SupportsGet | _SupportsSet | _SupportsDelete]:
     """Check if the object is a :external+python:term:`descriptor`."""
     return any(
-        callable(safe_getattr(x, item, None)) for item in ('__get__', '__set__', '__delete__')
+        callable(safe_getattr(x, item, None))
+        for item in ('__get__', '__set__', '__delete__')
     )
 
 
@@ -429,7 +426,10 @@ def object_description(obj: Any, *, _seen: frozenset[int] = frozenset()) -> str:
             sorted_keys = sorted(obj, key=lambda k: object_description(k, _seen=seen))
 
         items = (
-            (object_description(key, _seen=seen), object_description(obj[key], _seen=seen))
+            (
+                object_description(key, _seen=seen),
+                object_description(obj[key], _seen=seen),
+            )
             for key in sorted_keys
         )
         return '{%s}' % ', '.join(f'{key}: {value}' for (key, value) in items)
@@ -442,7 +442,9 @@ def object_description(obj: Any, *, _seen: frozenset[int] = frozenset()) -> str:
         except TypeError:
             # Cannot sort set values, fall back to using descriptions as a sort key
             sorted_values = sorted(obj, key=lambda x: object_description(x, _seen=seen))
-        return '{%s}' % ', '.join(object_description(x, _seen=seen) for x in sorted_values)
+        return '{%s}' % ', '.join(
+            object_description(x, _seen=seen) for x in sorted_values
+        )
     elif isinstance(obj, frozenset):
         if id(obj) in seen:
             return 'frozenset(...)'
@@ -760,7 +762,10 @@ def stringify_signature(
     args = []
     last_kind = None
     for param in sig.parameters.values():
-        if param.kind != Parameter.POSITIONAL_ONLY and last_kind == Parameter.POSITIONAL_ONLY:
+        if (
+            param.kind != Parameter.POSITIONAL_ONLY
+            and last_kind == Parameter.POSITIONAL_ONLY
+        ):
             # PEP-570: Separator for Positional Only Parameter: /
             args.append('/')
         if param.kind == Parameter.KEYWORD_ONLY and last_kind in (
@@ -797,7 +802,11 @@ def stringify_signature(
         args.append('/')
 
     concatenated_args = ', '.join(args)
-    if sig.return_annotation is EMPTY or not show_annotation or not show_return_annotation:
+    if (
+        sig.return_annotation is EMPTY
+        or not show_annotation
+        or not show_return_annotation
+    ):
         return f'({concatenated_args})'
     else:
         retann = stringify_annotation(sig.return_annotation, mode)  # type: ignore[arg-type]
@@ -842,11 +851,15 @@ def signature_from_ast(node: ast.FunctionDef, code: str = '') -> Signature:
 
     # normal arguments
     for arg, defexpr in zip(args.args, defaults[pos_only_offset:], strict=False):
-        params.append(_define(Parameter.POSITIONAL_OR_KEYWORD, arg, code, defexpr=defexpr))
+        params.append(
+            _define(Parameter.POSITIONAL_OR_KEYWORD, arg, code, defexpr=defexpr)
+        )
 
     # variadic positional argument (no possible default expression)
     if args.vararg:
-        params.append(_define(Parameter.VAR_POSITIONAL, args.vararg, code, defexpr=None))
+        params.append(
+            _define(Parameter.VAR_POSITIONAL, args.vararg, code, defexpr=None)
+        )
 
     # keyword-only arguments
     for arg, defexpr in zip(args.kwonlyargs, args.kw_defaults, strict=False):
diff --git a/sphinx/util/inventory.py b/sphinx/util/inventory.py
index 909d14983c5..ab6c5ba7e7b 100644
--- a/sphinx/util/inventory.py
+++ b/sphinx/util/inventory.py
@@ -1,4 +1,5 @@
 """Inventory utility functions for Sphinx."""
+
 from __future__ import annotations
 
 import os
@@ -41,7 +42,7 @@ def readline(self) -> str:
         pos = self.buffer.find(b'\n')
         if pos != -1:
             line = self.buffer[:pos].decode()
-            self.buffer = self.buffer[pos + 1:]
+            self.buffer = self.buffer[pos + 1 :]
         elif self.eof:
             line = self.buffer.decode()
             self.buffer = b''
@@ -72,7 +73,7 @@ def read_compressed_lines(self) -> Iterator[str]:
             pos = buf.find(b'\n')
             while pos != -1:
                 yield buf[:pos].decode()
-                buf = buf[pos + 1:]
+                buf = buf[pos + 1 :]
                 pos = buf.find(b'\n')
 
 
@@ -135,8 +136,11 @@ def load_v2(
 
         for line in stream.read_compressed_lines():
             # be careful to handle names with embedded spaces correctly
-            m = re.match(r'(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
-                         line.rstrip(), flags=re.VERBOSE)
+            m = re.match(
+                r'(.+?)\s+(\S+)\s+(-?\d+)\s+?(\S*)\s+(.*)',
+                line.rstrip(),
+                flags=re.VERBOSE,
+            )
             if not m:
                 continue
             name, type, prio, location, dispname = m.groups()
@@ -155,15 +159,20 @@ def load_v2(
                 # Some types require case insensitive matches:
                 # * 'term': https://github.com/sphinx-doc/sphinx/issues/9291
                 # * 'label': https://github.com/sphinx-doc/sphinx/issues/12008
-                definition = f"{type}:{name}"
+                definition = f'{type}:{name}'
                 content = prio, location, dispname
                 lowercase_definition = definition.lower()
                 if lowercase_definition in potential_ambiguities:
                     if potential_ambiguities[lowercase_definition] != content:
                         actual_ambiguities.add(definition)
                     else:
-                        logger.debug(__("inventory <%s> contains duplicate definitions of %s"),
-                                     uri, definition, type='intersphinx',  subtype='external')
+                        logger.debug(
+                            __('inventory <%s> contains duplicate definitions of %s'),
+                            uri,
+                            definition,
+                            type='intersphinx',
+                            subtype='external',
+                        )
                 else:
                     potential_ambiguities[lowercase_definition] = content
             if location.endswith('$'):
@@ -172,25 +181,35 @@ def load_v2(
             inv_item: InventoryItem = projname, version, location, dispname
             invdata.setdefault(type, {})[name] = inv_item
         for ambiguity in actual_ambiguities:
-            logger.info(__("inventory <%s> contains multiple definitions for %s"),
-                        uri, ambiguity, type='intersphinx',  subtype='external')
+            logger.info(
+                __('inventory <%s> contains multiple definitions for %s'),
+                uri,
+                ambiguity,
+                type='intersphinx',
+                subtype='external',
+            )
         return invdata
 
     @classmethod
     def dump(
-        cls: type[InventoryFile], filename: str, env: BuildEnvironment, builder: Builder,
+        cls: type[InventoryFile],
+        filename: str,
+        env: BuildEnvironment,
+        builder: Builder,
     ) -> None:
         def escape(string: str) -> str:
-            return re.sub("\\s+", " ", string)
+            return re.sub('\\s+', ' ', string)
 
         with open(os.path.join(filename), 'wb') as f:
             # header
-            f.write(('# Sphinx inventory version 2\n'
-                     '# Project: %s\n'
-                     '# Version: %s\n'
-                     '# The remainder of this file is compressed using zlib.\n' %
-                     (escape(env.config.project),
-                      escape(env.config.version))).encode())
+            f.write(
+                (
+                    '# Sphinx inventory version 2\n'
+                    f'# Project: {escape(env.config.project)}\n'
+                    f'# Version: {escape(env.config.version)}\n'
+                    '# The remainder of this file is compressed using zlib.\n'
+                ).encode()
+            )
 
             # body
             compressor = zlib.compressobj(9)
@@ -205,7 +224,6 @@ def escape(string: str) -> str:
                         uri += '#' + anchor
                     if dispname == fullname:
                         dispname = '-'
-                    entry = ('%s %s:%s %s %s %s\n' %
-                             (fullname, domain.name, type, prio, uri, dispname))
+                    entry = f'{fullname} {domain.name}:{type} {prio} {uri} {dispname}\n'
                     f.write(compressor.compress(entry.encode()))
             f.write(compressor.flush())
diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py
index 804ef62ccb4..758a48f8b0e 100644
--- a/sphinx/util/logging.py
+++ b/sphinx/util/logging.py
@@ -27,27 +27,36 @@
 NAMESPACE = 'sphinx'
 VERBOSE = 15
 
-LEVEL_NAMES: defaultdict[str, int] = defaultdict(lambda: logging.WARNING, {
-    'CRITICAL': logging.CRITICAL,
-    'SEVERE': logging.CRITICAL,
-    'ERROR': logging.ERROR,
-    'WARNING': logging.WARNING,
-    'INFO': logging.INFO,
-    'VERBOSE': VERBOSE,
-    'DEBUG': logging.DEBUG,
-})
-
-VERBOSITY_MAP: defaultdict[int, int] = defaultdict(lambda: logging.NOTSET, {
-    0: logging.INFO,
-    1: VERBOSE,
-    2: logging.DEBUG,
-})
-
-COLOR_MAP: defaultdict[int, str] = defaultdict(lambda: 'blue', {
-    logging.ERROR: 'darkred',
-    logging.WARNING: 'red',
-    logging.DEBUG: 'darkgray',
-})
+LEVEL_NAMES: defaultdict[str, int] = defaultdict(
+    lambda: logging.WARNING,
+    {
+        'CRITICAL': logging.CRITICAL,
+        'SEVERE': logging.CRITICAL,
+        'ERROR': logging.ERROR,
+        'WARNING': logging.WARNING,
+        'INFO': logging.INFO,
+        'VERBOSE': VERBOSE,
+        'DEBUG': logging.DEBUG,
+    },
+)
+
+VERBOSITY_MAP: defaultdict[int, int] = defaultdict(
+    lambda: logging.NOTSET,
+    {
+        0: logging.INFO,
+        1: VERBOSE,
+        2: logging.DEBUG,
+    },
+)
+
+COLOR_MAP: defaultdict[int, str] = defaultdict(
+    lambda: 'blue',
+    {
+        logging.ERROR: 'darkred',
+        logging.WARNING: 'red',
+        logging.DEBUG: 'darkgray',
+    },
+)
 
 
 def getLogger(name: str) -> SphinxLoggerAdapter:
@@ -126,7 +135,7 @@ class SphinxLoggerAdapter(logging.LoggerAdapter):
     KEYWORDS = ['type', 'subtype', 'location', 'nonl', 'color', 'once']
 
     def log(  # type: ignore[override]
-        self, level: int | str, msg: str, *args: Any, **kwargs: Any,
+        self, level: int | str, msg: str, *args: Any, **kwargs: Any
     ) -> None:
         if isinstance(level, int):
             super().log(level, msg, *args, **kwargs)
@@ -400,14 +409,14 @@ def filter(self, record: logging.LogRecord) -> NoReturn:
         except (TypeError, ValueError):
             message = record.msg  # use record.msg itself
         if location := getattr(record, 'location', ''):
-            message = f"{location}:{message}"
+            message = f'{location}:{message}'
         if record.exc_info is not None:
             raise SphinxWarning(message) from record.exc_info[1]
         raise SphinxWarning(message)
 
 
 def is_suppressed_warning(
-    warning_type: str, sub_type: str, suppress_warnings: Set[str] | Sequence[str],
+    warning_type: str, sub_type: str, suppress_warnings: Set[str] | Sequence[str]
 ) -> bool:
     """Check whether the warning is suppressed or not."""
     if warning_type is None or len(suppress_warnings) == 0:
@@ -546,11 +555,11 @@ def filter(self, record: SphinxWarningLogRecord) -> bool:  # type: ignore[overri
 def get_node_location(node: Node) -> str | None:
     source, line = get_source_line(node)
     if source and line:
-        return f"{abspath(source)}:{line}"
+        return f'{abspath(source)}:{line}'
     if source:
-        return f"{abspath(source)}:"
+        return f'{abspath(source)}:'
     if line:
-        return f"<unknown>:{line}"
+        return f'<unknown>:{line}'
     return None
 
 
@@ -580,7 +589,9 @@ def write(self, data: str) -> None:
         except UnicodeEncodeError:
             # stream accept only str, not bytes.  So, we encode and replace
             # non-encodable characters, then decode them.
-            self.stream.write(data.encode(self.encoding, 'replace').decode(self.encoding))
+            self.stream.write(
+                data.encode(self.encoding, 'replace').decode(self.encoding)
+            )
 
     def flush(self) -> None:
         if hasattr(self.stream, 'flush'):
diff --git a/sphinx/util/matching.py b/sphinx/util/matching.py
index 79c56dd2e02..0ab75c47d0f 100644
--- a/sphinx/util/matching.py
+++ b/sphinx/util/matching.py
@@ -112,7 +112,7 @@ def patfilter(names: Iterable[str], pat: str) -> list[str]:
 
 def get_matching_files(
     dirname: str | os.PathLike[str],
-    include_patterns: Iterable[str] = ("**",),
+    include_patterns: Iterable[str] = ('**',),
     exclude_patterns: Iterable[str] = (),
 ) -> Iterator[str]:
     """Get all file names in a directory, recursively.
@@ -132,8 +132,8 @@ def get_matching_files(
 
     for root, dirs, files in os.walk(dirname, followlinks=True):
         relative_root = os.path.relpath(root, dirname)
-        if relative_root == ".":
-            relative_root = ""  # suppress dirname for files on the target dir
+        if relative_root == '.':
+            relative_root = ''  # suppress dirname for files on the target dir
 
         # Filter files
         included_files = []
diff --git a/sphinx/util/math.py b/sphinx/util/math.py
index 576fdcf5331..f482e0c4dac 100644
--- a/sphinx/util/math.py
+++ b/sphinx/util/math.py
@@ -14,7 +14,7 @@ def get_node_equation_number(writer: HTML5Translator, node: nodes.math_block) ->
     if writer.builder.config.math_numfig and writer.builder.config.numfig:
         figtype = 'displaymath'
         if writer.builder.name == 'singlehtml':
-            key = f"{writer.docnames[-1]}/{figtype}"  # type: ignore[has-type]
+            key = f'{writer.docnames[-1]}/{figtype}'  # type: ignore[has-type]
         else:
             key = figtype
 
diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py
index 01ce81290d4..d8f2b82071c 100644
--- a/sphinx/util/nodes.py
+++ b/sphinx/util/nodes.py
@@ -35,7 +35,7 @@
 caption_ref_re = explicit_title_re  # b/w compat alias
 
 
-N = TypeVar("N", bound=Node)
+N = TypeVar('N', bound=Node)
 
 
 class NodeMatcher(Generic[N]):
@@ -135,8 +135,11 @@ def apply_source_workaround(node: Element) -> None:
     # * rawsource of term node will have: ``term text : classifier1 : classifier2``
     # * rawsource of classifier node will be None
     if isinstance(node, nodes.classifier) and not node.rawsource:
-        logger.debug('[i18n] PATCH: %r to have source, line and rawsource: %s',
-                     get_full_module_name(node), repr_domxml(node))
+        logger.debug(
+            '[i18n] PATCH: %r to have source, line and rawsource: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         definition_list_item = node.parent
         node.source = definition_list_item.source
         node.line = definition_list_item.line - 1  # type: ignore[operator]
@@ -145,24 +148,37 @@ def apply_source_workaround(node: Element) -> None:
         # docutils-0.15 fills in rawsource attribute, but not in source.
         node.source = node.parent.source
     if isinstance(node, nodes.image) and node.source is None:
-        logger.debug('[i18n] PATCH: %r to have source, line: %s',
-                     get_full_module_name(node), repr_domxml(node))
+        logger.debug(
+            '[i18n] PATCH: %r to have source, line: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         node.source, node.line = node.parent.source, node.parent.line
     if isinstance(node, nodes.title) and node.source is None:
-        logger.debug('[i18n] PATCH: %r to have source: %s',
-                     get_full_module_name(node), repr_domxml(node))
+        logger.debug(
+            '[i18n] PATCH: %r to have source: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         node.source, node.line = node.parent.source, node.parent.line
     if isinstance(node, nodes.term):
-        logger.debug('[i18n] PATCH: %r to have rawsource: %s',
-                     get_full_module_name(node), repr_domxml(node))
+        logger.debug(
+            '[i18n] PATCH: %r to have rawsource: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         # strip classifier from rawsource of term
         for classifier in reversed(list(node.parent.findall(nodes.classifier))):
-            node.rawsource = re.sub(r'\s*:\s*%s' % re.escape(classifier.astext()),
-                                    '', node.rawsource)
+            node.rawsource = re.sub(
+                r'\s*:\s*%s' % re.escape(classifier.astext()), '', node.rawsource
+            )
     if isinstance(node, nodes.topic) and node.source is None:
         # docutils-0.18 does not fill the source attribute of topic
-        logger.debug('[i18n] PATCH: %r to have source, line: %s',
-                     get_full_module_name(node), repr_domxml(node))
+        logger.debug(
+            '[i18n] PATCH: %r to have source, line: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         node.source, node.line = node.parent.source, node.parent.line
 
     # workaround: literal_block under bullet list (#4913)
@@ -178,14 +194,20 @@ def apply_source_workaround(node: Element) -> None:
         return
 
     # workaround: some docutils nodes doesn't have source, line.
-    if isinstance(node, (
-        nodes.rubric  # #1305 rubric directive
-        | nodes.line  # #1477 line node
-        | nodes.image  # #3093 image directive in substitution
-        | nodes.field_name  # #3335 field list syntax
-    )):
-        logger.debug('[i18n] PATCH: %r to have source and line: %s',
-                     get_full_module_name(node), repr_domxml(node))
+    if isinstance(
+        node,
+        (
+            nodes.rubric  # #1305 rubric directive
+            | nodes.line  # #1477 line node
+            | nodes.image  # #3093 image directive in substitution
+            | nodes.field_name  # #3335 field list syntax
+        ),
+    ):
+        logger.debug(
+            '[i18n] PATCH: %r to have source and line: %s',
+            get_full_module_name(node),
+            repr_domxml(node),
+        )
         try:
             node.source = get_node_source(node)
         except ValueError:
@@ -217,24 +239,36 @@ def is_translatable(node: Node) -> bool:
 
     if isinstance(node, nodes.TextElement):
         if not node.source:
-            logger.debug('[i18n] SKIP %r because no node.source: %s',
-                         get_full_module_name(node), repr_domxml(node))
+            logger.debug(
+                '[i18n] SKIP %r because no node.source: %s',
+                get_full_module_name(node),
+                repr_domxml(node),
+            )
             return False  # built-in message
         if isinstance(node, IGNORED_NODES) and 'translatable' not in node:
-            logger.debug("[i18n] SKIP %r because node is in IGNORED_NODES "
-                         "and no node['translatable']: %s",
-                         get_full_module_name(node), repr_domxml(node))
+            logger.debug(
+                '[i18n] SKIP %r because node is in IGNORED_NODES '
+                "and no node['translatable']: %s",
+                get_full_module_name(node),
+                repr_domxml(node),
+            )
             return False
         if not node.get('translatable', True):
             # not(node['translatable'] == True or node['translatable'] is None)
-            logger.debug("[i18n] SKIP %r because not node['translatable']: %s",
-                         get_full_module_name(node), repr_domxml(node))
+            logger.debug(
+                "[i18n] SKIP %r because not node['translatable']: %s",
+                get_full_module_name(node),
+                repr_domxml(node),
+            )
             return False
         # <field_name>orphan</field_name>
         # XXX ignore all metadata (== docinfo)
         if isinstance(node, nodes.field_name) and (node.children[0] == 'orphan'):
-            logger.debug('[i18n] SKIP %r because orphan node: %s',
-                         get_full_module_name(node), repr_domxml(node))
+            logger.debug(
+                '[i18n] SKIP %r because orphan node: %s',
+                get_full_module_name(node),
+                repr_domxml(node),
+            )
             return False
         return True
 
@@ -249,7 +283,7 @@ def is_translatable(node: Node) -> bool:
 )
 IMAGE_TYPE_NODES = (
     nodes.image,
-)
+)  # fmt: skip
 
 
 def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
@@ -272,7 +306,7 @@ def extract_messages(doctree: Element) -> Iterable[tuple[Element, str]]:
             else:
                 msg = ''
         elif isinstance(node, nodes.meta):
-            msg = node["content"]
+            msg = node['content']
         else:
             msg = node.rawsource.replace('\n', ' ').strip()  # type: ignore[attr-defined]
 
@@ -325,8 +359,9 @@ def traverse_translatable_index(
         yield node, entries
 
 
-def nested_parse_with_titles(state: RSTState, content: StringList, node: Node,
-                             content_offset: int = 0) -> str:
+def nested_parse_with_titles(
+    state: RSTState, content: StringList, node: Node, content_offset: int = 0
+) -> str:
     """Version of state.nested_parse() that allows titles and does not require
     titles to have the same decoration as the calling document.
 
@@ -359,13 +394,13 @@ def split_explicit_title(text: str) -> tuple[bool, str, str]:
     return False, text, text
 
 
-indextypes = [
-    'single', 'pair', 'double', 'triple', 'see', 'seealso',
-]
+indextypes = ['single', 'pair', 'double', 'triple', 'see', 'seealso']
 
 
-def process_index_entry(entry: str, targetid: str,
-                        ) -> list[tuple[str, str, str, str, str | None]]:
+def process_index_entry(
+    entry: str,
+    targetid: str,
+) -> list[tuple[str, str, str, str, str | None]]:
     from sphinx.domains.python import pairindextypes
 
     indexentries: list[tuple[str, str, str, str, str | None]] = []
@@ -377,18 +412,25 @@ def process_index_entry(entry: str, targetid: str,
         entry = entry[1:].lstrip()
     for index_type in pairindextypes:
         if entry.startswith(f'{index_type}:'):
-            value = entry[len(index_type) + 1:].strip()
+            value = entry[len(index_type) + 1 :].strip()
             value = f'{pairindextypes[index_type]}; {value}'
             # xref RemovedInSphinx90Warning
-            logger.warning(__('%r is deprecated for index entries (from entry %r). '
-                              "Use 'pair: %s' instead."),
-                           index_type, entry, value, type='index')
+            logger.warning(
+                __(
+                    '%r is deprecated for index entries (from entry %r). '
+                    "Use 'pair: %s' instead."
+                ),
+                index_type,
+                entry,
+                value,
+                type='index',
+            )
             indexentries.append(('pair', value, targetid, main, None))
             break
     else:
         for index_type in indextypes:
             if entry.startswith(f'{index_type}:'):
-                value = entry[len(index_type) + 1:].strip()
+                value = entry[len(index_type) + 1 :].strip()
                 if index_type == 'double':
                     index_type = 'pair'
                 indexentries.append((index_type, value, targetid, main, None))
@@ -430,13 +472,22 @@ def inline_all_toctrees(
                 try:
                     traversed.append(includefile)
                     logger.info(indent + colorfunc(includefile))
-                    subtree = inline_all_toctrees(builder, docnameset, includefile,
-                                                  builder.env.get_doctree(includefile),
-                                                  colorfunc, traversed, indent)
+                    subtree = inline_all_toctrees(
+                        builder,
+                        docnameset,
+                        includefile,
+                        builder.env.get_doctree(includefile),
+                        colorfunc,
+                        traversed,
+                        indent,
+                    )
                     docnameset.add(includefile)
                 except Exception:
-                    logger.warning(__('toctree contains ref to nonexisting file %r'),
-                                   includefile, location=docname)
+                    logger.warning(
+                        __('toctree contains ref to nonexisting file %r'),
+                        includefile,
+                        location=docname,
+                    )
                 else:
                     sof = addnodes.start_of_file(docname=includefile)
                     sof.children = subtree.children
@@ -478,57 +529,61 @@ def _make_id(string: str) -> str:
 _non_id_chars = re.compile('[^a-zA-Z0-9._]+')
 _non_id_at_ends = re.compile('^[-0-9._]+|-+$')
 _non_id_translate = {
-    0x00f8: 'o',       # o with stroke
-    0x0111: 'd',       # d with stroke
-    0x0127: 'h',       # h with stroke
-    0x0131: 'i',       # dotless i
-    0x0142: 'l',       # l with stroke
-    0x0167: 't',       # t with stroke
-    0x0180: 'b',       # b with stroke
-    0x0183: 'b',       # b with topbar
-    0x0188: 'c',       # c with hook
-    0x018c: 'd',       # d with topbar
-    0x0192: 'f',       # f with hook
-    0x0199: 'k',       # k with hook
-    0x019a: 'l',       # l with bar
-    0x019e: 'n',       # n with long right leg
-    0x01a5: 'p',       # p with hook
-    0x01ab: 't',       # t with palatal hook
-    0x01ad: 't',       # t with hook
-    0x01b4: 'y',       # y with hook
-    0x01b6: 'z',       # z with stroke
-    0x01e5: 'g',       # g with stroke
-    0x0225: 'z',       # z with hook
-    0x0234: 'l',       # l with curl
-    0x0235: 'n',       # n with curl
-    0x0236: 't',       # t with curl
-    0x0237: 'j',       # dotless j
-    0x023c: 'c',       # c with stroke
-    0x023f: 's',       # s with swash tail
-    0x0240: 'z',       # z with swash tail
-    0x0247: 'e',       # e with stroke
-    0x0249: 'j',       # j with stroke
-    0x024b: 'q',       # q with hook tail
-    0x024d: 'r',       # r with stroke
-    0x024f: 'y',       # y with stroke
+    0x00F8: 'o',  # o with stroke
+    0x0111: 'd',  # d with stroke
+    0x0127: 'h',  # h with stroke
+    0x0131: 'i',  # dotless i
+    0x0142: 'l',  # l with stroke
+    0x0167: 't',  # t with stroke
+    0x0180: 'b',  # b with stroke
+    0x0183: 'b',  # b with topbar
+    0x0188: 'c',  # c with hook
+    0x018C: 'd',  # d with topbar
+    0x0192: 'f',  # f with hook
+    0x0199: 'k',  # k with hook
+    0x019A: 'l',  # l with bar
+    0x019E: 'n',  # n with long right leg
+    0x01A5: 'p',  # p with hook
+    0x01AB: 't',  # t with palatal hook
+    0x01AD: 't',  # t with hook
+    0x01B4: 'y',  # y with hook
+    0x01B6: 'z',  # z with stroke
+    0x01E5: 'g',  # g with stroke
+    0x0225: 'z',  # z with hook
+    0x0234: 'l',  # l with curl
+    0x0235: 'n',  # n with curl
+    0x0236: 't',  # t with curl
+    0x0237: 'j',  # dotless j
+    0x023C: 'c',  # c with stroke
+    0x023F: 's',  # s with swash tail
+    0x0240: 'z',  # z with swash tail
+    0x0247: 'e',  # e with stroke
+    0x0249: 'j',  # j with stroke
+    0x024B: 'q',  # q with hook tail
+    0x024D: 'r',  # r with stroke
+    0x024F: 'y',  # y with stroke
 }
 _non_id_translate_digraphs = {
-    0x00df: 'sz',      # ligature sz
-    0x00e6: 'ae',      # ae
-    0x0153: 'oe',      # ligature oe
-    0x0238: 'db',      # db digraph
-    0x0239: 'qp',      # qp digraph
+    0x00DF: 'sz',  # ligature sz
+    0x00E6: 'ae',  # ae
+    0x0153: 'oe',  # ligature oe
+    0x0238: 'db',  # db digraph
+    0x0239: 'qp',  # qp digraph
 }
 
 
-def make_id(env: BuildEnvironment, document: nodes.document,
-            prefix: str = '', term: str | None = None) -> str:
+def make_id(
+    env: BuildEnvironment,
+    document: nodes.document,
+    prefix: str = '',
+    term: str | None = None,
+) -> str:
     """Generate an appropriate node_id for given *prefix* and *term*."""
     node_id = None
     if prefix:
-        idformat = prefix + "-%s"
+        idformat = prefix + '-%s'
     else:
-        idformat = (document.settings.id_prefix or "id") + "%s"
+        idformat = (document.settings.id_prefix or 'id') + '%s'
 
     # try to generate node_id by *term*
     if prefix and term:
@@ -547,27 +602,36 @@ def make_id(env: BuildEnvironment, document: nodes.document,
     return node_id
 
 
-def find_pending_xref_condition(node: addnodes.pending_xref, condition: str,
-                                ) -> Element | None:
+def find_pending_xref_condition(
+    node: addnodes.pending_xref, condition: str
+) -> Element | None:
     """Pick matched pending_xref_condition node up from the pending_xref."""
     for subnode in node:
-        if (isinstance(subnode, addnodes.pending_xref_condition) and
-                subnode.get('condition') == condition):
+        if (
+            isinstance(subnode, addnodes.pending_xref_condition)
+            and subnode.get('condition') == condition
+        ):
             return subnode
     return None
 
 
-def make_refnode(builder: Builder, fromdocname: str, todocname: str, targetid: str | None,
-                 child: Node | list[Node], title: str | None = None,
-                 ) -> nodes.reference:
+def make_refnode(
+    builder: Builder,
+    fromdocname: str,
+    todocname: str,
+    targetid: str | None,
+    child: Node | list[Node],
+    title: str | None = None,
+) -> nodes.reference:
     """Shortcut to create a reference node."""
     node = nodes.reference('', '', internal=True)
     if fromdocname == todocname and targetid:
         node['refid'] = targetid
     else:
         if targetid:
-            node['refuri'] = (builder.get_relative_uri(fromdocname, todocname) +
-                              '#' + targetid)
+            node['refuri'] = (
+                builder.get_relative_uri(fromdocname, todocname) + '#' + targetid
+            )
         else:
             node['refuri'] = builder.get_relative_uri(fromdocname, todocname)
     if title:
@@ -577,8 +641,9 @@ def make_refnode(builder: Builder, fromdocname: str, todocname: str, targetid: s
 
 
 def set_source_info(directive: Directive, node: Node) -> None:
-    node.source, node.line = \
-        directive.state_machine.get_source_and_line(directive.lineno)
+    node.source, node.line = directive.state_machine.get_source_and_line(
+        directive.lineno
+    )
 
 
 def set_role_source_info(inliner: Inliner, lineno: int, node: Node) -> None:
@@ -635,7 +700,8 @@ def _only_node_keep_children(node: addnodes.only, tags: Tags) -> bool:
         logger.warning(
             __('exception while evaluating only directive expression: %s'),
             err,
-            location=node)
+            location=node,
+        )
         return True
 
 
@@ -651,10 +717,10 @@ def _copy_except__document(el: Element) -> Element:
     newnode.rawsource = el.rawsource
     newnode.tagname = el.tagname
     # copied in Element.copy()
-    newnode.attributes = {k: (v
-                              if k not in {'ids', 'classes', 'names', 'dupnames', 'backrefs'}
-                              else v[:])
-                          for k, v in el.attributes.items()}
+    newnode.attributes = {
+        k: (v if k not in {'ids', 'classes', 'names', 'dupnames', 'backrefs'} else v[:])
+        for k, v in el.attributes.items()
+    }
     newnode.line = el.line
     newnode.source = el.source
     return newnode
diff --git a/sphinx/util/osutil.py b/sphinx/util/osutil.py
index d5d6ab5bc3f..64f07a43249 100644
--- a/sphinx/util/osutil.py
+++ b/sphinx/util/osutil.py
@@ -25,7 +25,7 @@
 # Define SEP as a manifest constant, not so much because we expect it to change
 # in the future as to avoid the suspicion that a stray "/" in the code is a
 # hangover from more *nix-oriented origins.
-SEP = "/"
+SEP = '/'
 
 
 def os_path(canonical_path: str, /) -> str:
@@ -115,21 +115,23 @@ def copyfile(
         raise FileNotFoundError(msg)
 
     if (
-        not (dest_exists := dest.exists()) or
+        not (dest_exists := dest.exists())
         # comparison must be done using shallow=False since
         # two different files might have the same size
-        not filecmp.cmp(source, dest, shallow=False)
+        or not filecmp.cmp(source, dest, shallow=False)
     ):
         if not force and dest_exists:
             # sphinx.util.logging imports sphinx.util.osutil,
             # so use a local import to avoid circular imports
             from sphinx.util import logging
+
             logger = logging.getLogger(__name__)
 
-            msg = __('Aborted attempted copy from %s to %s '
-                     '(the destination path has existing data).')
-            logger.warning(msg, source, dest,
-                           type='misc', subtype='copy_overwrite')
+            msg = __(
+                'Aborted attempted copy from %s to %s '
+                '(the destination path has existing data).'
+            )
+            logger.warning(msg, source, dest, type='misc', subtype='copy_overwrite')
             return
 
         shutil.copyfile(source, dest)
@@ -149,8 +151,9 @@ def make_filename_from_project(project: str) -> str:
     return make_filename(project.removesuffix(' Documentation')).lower()
 
 
-def relpath(path: str | os.PathLike[str],
-            start: str | os.PathLike[str] | None = os.curdir) -> str:
+def relpath(
+    path: str | os.PathLike[str], start: str | os.PathLike[str] | None = os.curdir
+) -> str:
     """Return a relative filepath to *path* either from the current directory or
     from an optional *start* directory.
 
@@ -241,7 +244,7 @@ def __enter__(self) -> FileAvoidWrite:
         return self
 
     def __exit__(
-        self, exc_type: type[Exception], exc_value: Exception, traceback: Any,
+        self, exc_type: type[Exception], exc_value: Exception, traceback: Any
     ) -> bool:
         self.close()
         return True
diff --git a/sphinx/util/parallel.py b/sphinx/util/parallel.py
index f17ef71294b..27ea0d591cc 100644
--- a/sphinx/util/parallel.py
+++ b/sphinx/util/parallel.py
@@ -10,6 +10,7 @@
 
 try:
     import multiprocessing
+
     HAS_MULTIPROCESSING = True
 except ImportError:
     HAS_MULTIPROCESSING = False
@@ -33,7 +34,7 @@ def __init__(self, nproc: int = 1) -> None:
         pass
 
     def add_task(
-        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None,
+        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None
     ) -> None:
         if arg is not None:
             res = task_func(arg)
@@ -83,7 +84,7 @@ def _process(self, pipe: Any, func: Callable, arg: Any) -> None:
         pipe.send((failed, collector.logs, ret))
 
     def add_task(
-        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None,
+        self, task_func: Callable, arg: Any = None, result_func: Callable | None = None
     ) -> None:
         tid = self._taskid
         self._taskid += 1
@@ -156,4 +157,4 @@ def make_chunks(arguments: Sequence[str], nproc: int, maxbatch: int = 10) -> lis
     if rest:
         nchunks += 1
     # partition documents in "chunks" that will be written by one Process
-    return [arguments[i * chunksize:(i + 1) * chunksize] for i in range(nchunks)]
+    return [arguments[i * chunksize : (i + 1) * chunksize] for i in range(nchunks)]
diff --git a/sphinx/util/parsing.py b/sphinx/util/parsing.py
index a8f937f8fe1..33893f8807c 100644
--- a/sphinx/util/parsing.py
+++ b/sphinx/util/parsing.py
@@ -53,7 +53,7 @@ def nested_parse_to_nodes(
     """
     document = state.document
     content = _text_to_string_list(
-        text, source=source, tab_width=document.settings.tab_width,
+        text, source=source, tab_width=document.settings.tab_width
     )
     node = Element()  # Anonymous container for parsing
     node.document = document
@@ -62,7 +62,9 @@ def nested_parse_to_nodes(
         state.nested_parse(content, offset, node, match_titles=allow_section_headings)
     else:
         with _fresh_title_style_context(state):
-            state.nested_parse(content, offset, node, match_titles=allow_section_headings)
+            state.nested_parse(
+                content, offset, node, match_titles=allow_section_headings
+            )
     return node.children
 
 
@@ -84,7 +86,7 @@ def _fresh_title_style_context(state: RSTState) -> Iterator[None]:
 
 
 def _text_to_string_list(
-    text: str | StringList, /, *, source: str, tab_width: int,
+    text: str | StringList, /, *, source: str, tab_width: int
 ) -> StringList:
     # Doesn't really belong in this module, but avoids circular imports.
     if isinstance(text, StringList):
diff --git a/sphinx/util/png.py b/sphinx/util/png.py
index 6c942194ecb..c90e27ec14e 100644
--- a/sphinx/util/png.py
+++ b/sphinx/util/png.py
@@ -10,13 +10,13 @@
 
 DEPTH_CHUNK_LEN = struct.pack('!i', 10)
 DEPTH_CHUNK_START = b'tEXtDepth\x00'
-IEND_CHUNK = b'\x00\x00\x00\x00IEND\xAE\x42\x60\x82'
+IEND_CHUNK = b'\x00\x00\x00\x00IEND\xae\x42\x60\x82'
 
 
 def read_png_depth(filename: str) -> int | None:
     """Read the special tEXt chunk indicating the depth from a PNG file."""
     with open(filename, 'rb') as f:
-        f.seek(- (LEN_IEND + LEN_DEPTH), 2)
+        f.seek(-(LEN_IEND + LEN_DEPTH), 2)
         depthchunk = f.read(LEN_DEPTH)
         if not depthchunk.startswith(DEPTH_CHUNK_LEN + DEPTH_CHUNK_START):
             # either not a PNG file or not containing the depth chunk
@@ -37,7 +37,7 @@ def write_png_depth(filename: str, depth: int) -> None:
         # overwrite it with the depth chunk
         f.write(DEPTH_CHUNK_LEN + DEPTH_CHUNK_START + data)
         # calculate the checksum over chunk name and data
-        crc = binascii.crc32(DEPTH_CHUNK_START + data) & 0xffffffff
+        crc = binascii.crc32(DEPTH_CHUNK_START + data) & 0xFFFFFFFF
         f.write(struct.pack('!I', crc))
         # replace the IEND chunk
         f.write(IEND_CHUNK)
diff --git a/sphinx/util/requests.py b/sphinx/util/requests.py
index 7c64e940dfc..a647bf5ba50 100644
--- a/sphinx/util/requests.py
+++ b/sphinx/util/requests.py
@@ -11,8 +11,10 @@
 
 import sphinx
 
-_USER_AGENT = (f'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 '
-               f'Sphinx/{sphinx.__version__}')
+_USER_AGENT = (
+    f'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 '
+    f'Sphinx/{sphinx.__version__}'
+)
 
 
 def _get_tls_cacert(url: str, certs: str | dict[str, str] | None) -> str | bool:
@@ -49,7 +51,9 @@ def head(url: str, **kwargs: Any) -> requests.Response:
 
 class _Session(requests.Session):
     def request(  # type: ignore[override]
-        self, method: str, url: str,
+        self,
+        method: str,
+        url: str,
         _user_agent: str = '',
         _tls_info: tuple[bool, str | dict[str, str] | None] = (),  # type: ignore[assignment]
         **kwargs: Any,
@@ -72,5 +76,5 @@ def request(  # type: ignore[override]
 
         with warnings.catch_warnings():
             # ignore InsecureRequestWarning if verify=False
-            warnings.filterwarnings("ignore", category=InsecureRequestWarning)
+            warnings.filterwarnings('ignore', category=InsecureRequestWarning)
             return super().request(method, url, **kwargs)
diff --git a/sphinx/util/rst.py b/sphinx/util/rst.py
index 4e8fdee2ed7..85915ef894b 100644
--- a/sphinx/util/rst.py
+++ b/sphinx/util/rst.py
@@ -29,8 +29,8 @@
 SECTIONING_CHARS = ['=', '-', '~']
 
 # width of characters
-WIDECHARS: dict[str, str] = defaultdict(lambda: "WF")  # WF: Wide + Full-width
-WIDECHARS["ja"] = "WFA"  # In Japanese, Ambiguous characters also have double width
+WIDECHARS: dict[str, str] = defaultdict(lambda: 'WF')  # WF: Wide + Full-width
+WIDECHARS['ja'] = 'WFA'  # In Japanese, Ambiguous characters also have double width
 
 
 def escape(text: str) -> str:
@@ -41,6 +41,7 @@ def escape(text: str) -> str:
 
 def textwidth(text: str, widechars: str = 'WF') -> int:
     """Get width of text."""
+
     def charwidth(char: str, widechars: str) -> int:
         if east_asian_width(char) in widechars:
             return 2
@@ -103,7 +104,8 @@ def append_epilog(content: StringList, epilog: str) -> None:
     if epilog:
         if len(content) > 0:
             source, lineno = content.info(-1)
-            lineno = cast(int, lineno)  # lineno will never be None, since len(content) > 0
+            # lineno will never be None, since len(content) > 0
+            lineno = cast(int, lineno)
         else:
             source = '<generated>'
             lineno = 0
diff --git a/sphinx/util/tags.py b/sphinx/util/tags.py
index 71492dc9a15..7d9c72b2e85 100644
--- a/sphinx/util/tags.py
+++ b/sphinx/util/tags.py
@@ -69,8 +69,11 @@ def remove(self, tag: str) -> None:
 
     @property
     def tags(self) -> dict[str, Literal[True]]:
-        warnings.warn('Tags.tags is deprecated, use methods on Tags.',
-                      RemovedInSphinx90Warning, stacklevel=2)
+        warnings.warn(
+            'Tags.tags is deprecated, use methods on Tags.',
+            RemovedInSphinx90Warning,
+            stacklevel=2,
+        )
         return dict.fromkeys(self._tags, True)
 
     def eval_condition(self, condition: str) -> bool:
diff --git a/sphinx/util/template.py b/sphinx/util/template.py
index 1cfc287a821..6e217d6177f 100644
--- a/sphinx/util/template.py
+++ b/sphinx/util/template.py
@@ -49,7 +49,7 @@ def __init__(self, search_path: Sequence[str | os.PathLike[str]]) -> None:
 
     @classmethod
     def render_from_file(
-        cls: type[FileRenderer], filename: str, context: dict[str, Any],
+        cls: type[FileRenderer], filename: str, context: dict[str, Any]
     ) -> str:
         dirname = os.path.dirname(filename)
         basename = os.path.basename(filename)
@@ -57,21 +57,26 @@ def render_from_file(
 
 
 class SphinxRenderer(FileRenderer):
-    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None) -> None:
+    def __init__(
+        self, template_path: Sequence[str | os.PathLike[str]] | None = None
+    ) -> None:
         if template_path is None:
             template_path = os.path.join(package_dir, 'templates')
         super().__init__(template_path)
 
     @classmethod
     def render_from_file(
-        cls: type[FileRenderer], filename: str, context: dict[str, Any],
+        cls: type[FileRenderer], filename: str, context: dict[str, Any]
     ) -> str:
         return FileRenderer.render_from_file(filename, context)
 
 
 class LaTeXRenderer(SphinxRenderer):
-    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None,
-                 latex_engine: str | None = None) -> None:
+    def __init__(
+        self,
+        template_path: Sequence[str | os.PathLike[str]] | None = None,
+        latex_engine: str | None = None,
+    ) -> None:
         if template_path is None:
             template_path = [os.path.join(package_dir, 'templates', 'latex')]
         super().__init__(template_path)
@@ -93,8 +98,11 @@ def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None
 
 
 class ReSTRenderer(SphinxRenderer):
-    def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None,
-                 language: str | None = None) -> None:
+    def __init__(
+        self,
+        template_path: Sequence[str | os.PathLike[str]] | None = None,
+        language: str | None = None,
+    ) -> None:
         super().__init__(template_path)
 
         # add language to environment
@@ -109,9 +117,12 @@ def __init__(self, template_path: Sequence[str | os.PathLike[str]] | None = None
 class SphinxTemplateLoader(BaseLoader):
     """A loader supporting template inheritance"""
 
-    def __init__(self, confdir: str | os.PathLike[str],
-                 templates_paths: Sequence[str | os.PathLike[str]],
-                 system_templates_paths: Sequence[str | os.PathLike[str]]) -> None:
+    def __init__(
+        self,
+        confdir: str | os.PathLike[str],
+        templates_paths: Sequence[str | os.PathLike[str]],
+        system_templates_paths: Sequence[str | os.PathLike[str]],
+    ) -> None:
         self.loaders = []
         self.sysloaders = []
 
diff --git a/sphinx/util/texescape.py b/sphinx/util/texescape.py
index 8527441d7fe..57d35450e60 100644
--- a/sphinx/util/texescape.py
+++ b/sphinx/util/texescape.py
@@ -47,8 +47,8 @@
     # complications (whether by {}, or a macro) and is not done
     # the next two require textcomp package
     ("'", r'\textquotesingle{}'),  # else ' renders curly, and '' is a ligature
-    ('`', r'\textasciigrave{}'),   # else \` and \`\` render curly
-    ('<', r'\textless{}'),     # < is inv. exclam in OT1, << is a T1-ligature
+    ('`', r'\textasciigrave{}'),  # else \` and \`\` render curly
+    ('<', r'\textless{}'),  # < is inv. exclam in OT1, << is a T1-ligature
     ('>', r'\textgreater{}'),  # > is inv. quest. mark in 0T1, >> a T1-ligature
 ]
 
diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py
index 31dfa8f2940..35d444aa583 100644
--- a/sphinx/util/typing.py
+++ b/sphinx/util/typing.py
@@ -92,8 +92,9 @@ def is_invalid_builtin_class(obj: Any) -> bool:
 
 # common role functions
 if TYPE_CHECKING:
+
     class RoleFunction(Protocol):
-        def __call__(
+        def __call__(  # NoQA: E704
             self,
             name: str,
             rawtext: str,
@@ -103,8 +104,8 @@ def __call__(
             /,
             options: dict[str, Any] | None = None,
             content: Sequence[str] = (),
-        ) -> tuple[list[nodes.Node], list[nodes.system_message]]:
-            ...
+        ) -> tuple[list[nodes.Node], list[nodes.system_message]]: ...
+
 else:
     RoleFunction: TypeAlias = Callable[
         [str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
@@ -126,19 +127,17 @@ def __call__(
     _T_co = TypeVar('_T_co', str, bytes, covariant=True)
 
     class _ReadableStream(Protocol[_T_co]):
-        def read(self, size: int = ...) -> _T_co:
-            ...
+        def read(self, size: int = ...) -> _T_co: ...  # NoQA: E704
 
-        def __enter__(self) -> Self:
-            ...
+        def __enter__(self) -> Self: ...  # NoQA: E704
 
-        def __exit__(
+        def __exit__(  # NoQA: E704
             self,
             exc_type: type[BaseException] | None,
             exc_val: BaseException | None,
-            exc_tb: TracebackType | None
-        ) -> None:
-            ...
+            exc_tb: TracebackType | None,
+        ) -> None: ...
+
 
 # inventory data on memory
 InventoryItem: TypeAlias = tuple[
@@ -189,7 +188,9 @@ def get_type_hints(
     from sphinx.util.inspect import safe_getattr  # lazy loading
 
     try:
-        return typing.get_type_hints(obj, globalns, localns, include_extras=include_extras)
+        return typing.get_type_hints(
+            obj, globalns, localns, include_extras=include_extras
+        )
     except NameError:
         # Failed to evaluate ForwardRef (maybe TYPE_CHECKING)
         return safe_getattr(obj, '__annotations__', {})
@@ -212,7 +213,10 @@ def is_system_TypeVar(typ: Any) -> bool:
 
 def _is_annotated_form(obj: Any) -> TypeIs[Annotated[Any, ...]]:
     """Check if *obj* is an annotated type."""
-    return typing.get_origin(obj) is Annotated or str(obj).startswith('typing.Annotated')
+    return (
+        typing.get_origin(obj) is Annotated
+        or str(obj).startswith('typing.Annotated')
+    )  # fmt: skip
 
 
 def _is_unpack_form(obj: Any) -> bool:
@@ -286,18 +290,21 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
                 elif dataclasses.is_dataclass(m):
                     # use restify for the repr of field values rather than repr
                     d_fields = ', '.join([
-                        fr"{f.name}=\ {restify(getattr(m, f.name), mode)}"
-                        for f in dataclasses.fields(m) if f.repr
+                        rf'{f.name}=\ {restify(getattr(m, f.name), mode)}'
+                        for f in dataclasses.fields(m)
+                        if f.repr
                     ])
-                    meta_args.append(fr'{restify(type(m), mode)}\ ({d_fields})')
+                    meta_args.append(rf'{restify(type(m), mode)}\ ({d_fields})')
                 else:
                     meta_args.append(repr(m))
             meta = ', '.join(meta_args)
             if sys.version_info[:2] <= (3, 11):
                 # Hardcoded to fix errors on Python 3.11 and earlier.
-                return fr':py:class:`~typing.Annotated`\ [{args}, {meta}]'
-            return (f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
-                    fr'\ [{args}, {meta}]')
+                return rf':py:class:`~typing.Annotated`\ [{args}, {meta}]'
+            return (
+                f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
+                rf'\ [{args}, {meta}]'
+            )
         elif isinstance(cls, NewType):
             return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'  # type: ignore[attr-defined]
         elif isinstance(cls, types.UnionType):
@@ -307,14 +314,14 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
         elif cls.__module__ in ('__builtin__', 'builtins'):
             if hasattr(cls, '__args__'):
                 if not cls.__args__:  # Empty tuple, list, ...
-                    return fr':py:class:`{cls.__name__}`\ [{cls.__args__!r}]'
+                    return rf':py:class:`{cls.__name__}`\ [{cls.__args__!r}]'
 
-                concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
-                return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
+                concatenated_args = ', '.join(
+                    restify(arg, mode) for arg in cls.__args__
+                )
+                return rf':py:class:`{cls.__name__}`\ [{concatenated_args}]'
             return f':py:class:`{cls.__name__}`'
-        elif (isgenericalias(cls)
-              and cls_module_is_typing
-              and cls.__origin__ is Union):
+        elif isgenericalias(cls) and cls_module_is_typing and cls.__origin__ is Union:
             # *cls* is defined in ``typing``, and thus ``__args__`` must exist
             return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif isgenericalias(cls):
@@ -338,19 +345,20 @@ def restify(cls: Any, mode: _RestifyMode = 'fully-qualified-except-typing') -> s
             if (
                 (cls_module_is_typing and cls.__name__ == 'Callable')
                 or (cls.__module__ == 'collections.abc' and cls.__name__ == 'Callable')
-            ):
+            ):  # fmt: skip
                 args = ', '.join(restify(a, mode) for a in __args__[:-1])
                 returns = restify(__args__[-1], mode)
-                return fr'{text}\ [[{args}], {returns}]'
+                return rf'{text}\ [[{args}], {returns}]'
 
             if cls_module_is_typing and cls.__origin__.__name__ == 'Literal':
-                args = ', '.join(_format_literal_arg_restify(a, mode=mode)
-                                 for a in cls.__args__)
-                return fr'{text}\ [{args}]'
+                args = ', '.join(
+                    _format_literal_arg_restify(a, mode=mode) for a in cls.__args__
+                )
+                return rf'{text}\ [{args}]'
 
             # generic representation of the parameters
             args = ', '.join(restify(a, mode) for a in __args__)
-            return fr'{text}\ [{args}]'
+            return rf'{text}\ [{args}]'
         elif isinstance(cls, typing._SpecialForm):
             return f':py:obj:`~{cls.__module__}.{cls.__name__}`'  # type: ignore[attr-defined]
         elif sys.version_info[:2] >= (3, 11) and cls is typing.Any:
@@ -375,7 +383,9 @@ def _format_literal_arg_restify(arg: Any, /, *, mode: str) -> str:
         enum_cls = arg.__class__
         if mode == 'smart' or enum_cls.__module__ == 'typing':
             # MyEnum.member
-            return f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+            return (
+                f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+            )
         # module.MyEnum.member
         return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
     return repr(arg)
@@ -431,7 +441,10 @@ def stringify_annotation(
     # Extract the annotation's base type by considering formattable cases
     if isinstance(annotation, TypeVar) and not _is_unpack_form(annotation):
         # typing_extensions.Unpack is incorrectly determined as a TypeVar
-        if annotation_module_is_typing and mode in {'fully-qualified-except-typing', 'smart'}:
+        if annotation_module_is_typing and mode in {
+            'fully-qualified-except-typing',
+            'smart',
+        }:
             return annotation_name
         return module_prefix + f'{annotation_module}.{annotation_name}'
     elif isinstance(annotation, NewType):
@@ -461,7 +474,9 @@ def stringify_annotation(
 
     module_prefix = f'{annotation_module}.'
     annotation_forward_arg: str | None = getattr(annotation, '__forward_arg__', None)
-    if annotation_qualname or (annotation_module_is_typing and not annotation_forward_arg):
+    if annotation_qualname or (
+        annotation_module_is_typing and not annotation_forward_arg
+    ):
         if mode == 'smart':
             module_prefix = f'~{module_prefix}'
         if annotation_module_is_typing and mode == 'fully-qualified-except-typing':
@@ -484,7 +499,8 @@ def stringify_annotation(
                 # in this case, we know that the annotation is a member
                 # of ``typing`` and all of them define ``__origin__``
                 qualname = stringify_annotation(
-                    annotation.__origin__, 'fully-qualified-except-typing',
+                    annotation.__origin__,
+                    'fully-qualified-except-typing',
                 ).replace('typing.', '')  # ex. Union
     elif annotation_qualname:
         qualname = annotation_qualname
@@ -505,21 +521,25 @@ def stringify_annotation(
         if (
             qualname in {'Union', 'types.UnionType'}
             and all(getattr(a, '__origin__', ...) is typing.Literal for a in annotation_args)
-        ):
+        ):  # fmt: skip
             # special case to flatten a Union of Literals into a literal
             flattened_args = typing.Literal[annotation_args].__args__  # type: ignore[attr-defined]
-            args = ', '.join(_format_literal_arg_stringify(a, mode=mode)
-                             for a in flattened_args)
+            args = ', '.join(
+                _format_literal_arg_stringify(a, mode=mode) for a in flattened_args
+            )
             return f'{module_prefix}Literal[{args}]'
         if qualname in {'Optional', 'Union', 'types.UnionType'}:
             return ' | '.join(stringify_annotation(a, mode) for a in annotation_args)
         elif qualname == 'Callable':
-            args = ', '.join(stringify_annotation(a, mode) for a in annotation_args[:-1])
+            args = ', '.join(
+                stringify_annotation(a, mode) for a in annotation_args[:-1]
+            )
             returns = stringify_annotation(annotation_args[-1], mode)
             return f'{module_prefix}Callable[[{args}], {returns}]'
         elif qualname == 'Literal':
-            args = ', '.join(_format_literal_arg_stringify(a, mode=mode)
-                             for a in annotation_args)
+            args = ', '.join(
+                _format_literal_arg_stringify(a, mode=mode) for a in annotation_args
+            )
             return f'{module_prefix}Literal[{args}]'
         elif _is_annotated_form(annotation):  # for py310+
             args = stringify_annotation(annotation_args[0], mode)
@@ -530,10 +550,13 @@ def stringify_annotation(
                 elif dataclasses.is_dataclass(m):
                     # use stringify_annotation for the repr of field values rather than repr
                     d_fields = ', '.join([
-                        f"{f.name}={stringify_annotation(getattr(m, f.name), mode)}"
-                        for f in dataclasses.fields(m) if f.repr
+                        f'{f.name}={stringify_annotation(getattr(m, f.name), mode)}'
+                        for f in dataclasses.fields(m)
+                        if f.repr
                     ])
-                    meta_args.append(f'{stringify_annotation(type(m), mode)}({d_fields})')
+                    meta_args.append(
+                        f'{stringify_annotation(type(m), mode)}({d_fields})'
+                    )
                 else:
                     meta_args.append(repr(m))
             meta = ', '.join(meta_args)
@@ -568,7 +591,7 @@ def _format_literal_arg_stringify(arg: Any, /, *, mode: str) -> str:
 
 # deprecated name -> (object to return, canonical path or empty string, removal version)
 _DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
-}
+}  # fmt: skip
 
 
 def __getattr__(name: str) -> Any:

From c3088ef1df3d6da8030c415417495e5b08cdd79f Mon Sep 17 00:00:00 2001
From: aiudirog <aiudirog@gmail.com>
Date: Fri, 4 Oct 2024 09:30:38 -0400
Subject: [PATCH 16/29] Fix call to ``safe_getattr()`` (#12959)

---
 sphinx/ext/autodoc/__init__.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 4f6e776d656..ed2b750f3c0 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1079,7 +1079,8 @@ def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
                 else:
                     logger.warning(__('missing attribute mentioned in :members: option: '
                                       'module %s, attribute %s'),
-                                   safe_getattr(self.object, '__name__', '???', name),
+                                   safe_getattr(self.object, '__name__', '???'),
+                                   name,
                                    type='autodoc')
             return False, ret
 

From 883faaa568e4b3a738f4f3d82ec5293772cc8023 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 14:37:05 +0100
Subject: [PATCH 17/29] Check the number of arguments passed to
 ``safe_getattr()`` (#12961)

---
 sphinx/util/inspect.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py
index 33340bb7182..194b79db527 100644
--- a/sphinx/util/inspect.py
+++ b/sphinx/util/inspect.py
@@ -389,6 +389,10 @@ def isgenericalias(obj: Any) -> TypeIs[types.GenericAlias]:
 
 def safe_getattr(obj: Any, name: str, *defargs: Any) -> Any:
     """A getattr() that turns all exceptions into AttributeErrors."""
+    if len(defargs) > 1:
+        msg = f'safe_getattr expected at most 3 arguments, got {len(defargs)}'
+        raise TypeError(msg)
+
     try:
         return getattr(obj, name, *defargs)
     except Exception as exc:

From 97fa70cce9059983bc1563834fcbe43602409dee Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 15:02:29 +0100
Subject: [PATCH 18/29] Enable automatic formatting for ``sphinx/_cli/``
 (#12962)

---
 .ruff.toml                 |  1 -
 sphinx/_cli/__init__.py    | 60 +++++++++++++++++++++++++-------------
 sphinx/_cli/util/colour.py |  3 ++
 sphinx/_cli/util/errors.py | 39 ++++++++++++++++++-------
 4 files changed, 71 insertions(+), 32 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index d81928fa549..7ab7cb70584 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -442,7 +442,6 @@ forced-separate = [
 preview = true
 quote-style = "single"
 exclude = [
-    "sphinx/_cli/*",
     "sphinx/addnodes.py",
     "sphinx/application.py",
     "sphinx/builders/*",
diff --git a/sphinx/_cli/__init__.py b/sphinx/_cli/__init__.py
index 1e9c9314738..3160f08373c 100644
--- a/sphinx/_cli/__init__.py
+++ b/sphinx/_cli/__init__.py
@@ -38,7 +38,9 @@
     from collections.abc import Callable, Iterable, Iterator, Sequence
     from typing import NoReturn, TypeAlias
 
-    _PARSER_SETUP: TypeAlias = Callable[[argparse.ArgumentParser], argparse.ArgumentParser]
+    _PARSER_SETUP: TypeAlias = Callable[
+        [argparse.ArgumentParser], argparse.ArgumentParser
+    ]
     _RUNNER: TypeAlias = Callable[[argparse.Namespace], int]
 
     from typing import Protocol
@@ -50,8 +52,7 @@ class _SubcommandModule(Protocol):
 
 
 # Map of command name to import path.
-_COMMANDS: dict[str, str] = {
-}
+_COMMANDS: dict[str, str] = {}
 
 
 def _load_subcommand_descriptions() -> Iterator[tuple[str, str]]:
@@ -61,7 +62,7 @@ def _load_subcommand_descriptions() -> Iterator[tuple[str, str]]:
             description = module.parser_description
         except AttributeError:
             # log an error here, but don't fail the full enumeration
-            print(f"Failed to load the description for {command}", file=sys.stderr)
+            print(f'Failed to load the description for {command}', file=sys.stderr)
         else:
             yield command, description.split('\n\n', 1)[0]
 
@@ -79,7 +80,8 @@ def format_help(self) -> str:
         ]
 
         if commands := list(_load_subcommand_descriptions()):
-            command_max_length = min(max(map(len, next(zip(*commands, strict=True), ()))), 22)
+            command_lengths = map(len, next(zip(*commands, strict=True), ()))
+            command_max_length = min(max(command_lengths), 22)
             help_fragments += [
                 '\n',
                 bold(underline(__('Commands:'))),
@@ -95,8 +97,11 @@ def format_help(self) -> str:
         # Uppercase the title of the Optionals group
         self._optionals.title = __('Options')
         for argument_group in self._action_groups[1:]:
-            if arguments := [action for action in argument_group._group_actions
-                             if action.help != argparse.SUPPRESS]:
+            if arguments := [
+                action
+                for action in argument_group._group_actions
+                if action.help != argparse.SUPPRESS
+            ]:
                 help_fragments += self._format_optional_arguments(
                     arguments,
                     argument_group.title or '',
@@ -104,7 +109,9 @@ def format_help(self) -> str:
 
         help_fragments += [
             '\n',
-            __('For more information, visit https://www.sphinx-doc.org/en/master/man/.'),
+            __(
+                'For more information, visit https://www.sphinx-doc.org/en/master/man/.'
+            ),
             '\n',
         ]
         return ''.join(help_fragments)
@@ -123,7 +130,7 @@ def _format_optional_arguments(
             opt = prefix + '  ' + ', '.join(map(bold, action.option_strings))
             if action.nargs != 0:
                 opt += ' ' + self._format_metavar(
-                    action.nargs, action.metavar, action.choices, action.dest,
+                    action.nargs, action.metavar, action.choices, action.dest
                 )
             yield opt
             yield '\n'
@@ -161,10 +168,11 @@ def _format_metavar(
         raise ValueError(msg)
 
     def error(self, message: str) -> NoReturn:
-        sys.stderr.write(__(
-            '{0}: error: {1}\n'
-            "Run '{0} --help' for information"  # NoQA: COM812
-        ).format(self.prog, message))
+        sys.stderr.write(
+            __(
+                '{0}: error: {1}\n' "Run '{0} --help' for information"  # NoQA: COM812
+            ).format(self.prog, message)
+        )
         raise SystemExit(2)
 
 
@@ -172,18 +180,23 @@ def _create_parser() -> _RootArgumentParser:
     parser = _RootArgumentParser(
         prog='sphinx',
         description=__('   Manage documentation with Sphinx.'),
-        epilog=__('For more information, visit https://www.sphinx-doc.org/en/master/man/.'),
+        epilog=__(
+            'For more information, visit https://www.sphinx-doc.org/en/master/man/.'
+        ),
         add_help=False,
         allow_abbrev=False,
     )
     parser.add_argument(
-        '-V', '--version',
+        '-V',
+        '--version',
         action='store_true',
         default=argparse.SUPPRESS,
         help=__('Show the version and exit.'),
     )
     parser.add_argument(
-        '-h', '-?', '--help',
+        '-h',
+        '-?',
+        '--help',
         action='store_true',
         default=argparse.SUPPRESS,
         help=__('Show this message and exit.'),
@@ -192,14 +205,16 @@ def _create_parser() -> _RootArgumentParser:
     # logging control
     log_control = parser.add_argument_group(__('Logging'))
     log_control.add_argument(
-        '-v', '--verbose',
+        '-v',
+        '--verbose',
         action='count',
         dest='verbosity',
         default=0,
         help=__('Increase verbosity (can be repeated)'),
     )
     log_control.add_argument(
-        '-q', '--quiet',
+        '-q',
+        '--quiet',
         action='store_const',
         dest='verbosity',
         const=-1,
@@ -235,6 +250,7 @@ def _parse_command(argv: Sequence[str] = ()) -> tuple[str, Sequence[str]]:
     # Handle '--version' or '-V' passed to the main command or any subcommand
     if 'version' in args or {'-V', '--version'}.intersection(command_argv):
         from sphinx import __display_version__
+
         sys.stderr.write(f'sphinx {__display_version__}\n')
         raise SystemExit(0)
 
@@ -245,8 +261,12 @@ def _parse_command(argv: Sequence[str] = ()) -> tuple[str, Sequence[str]]:
         raise SystemExit(0)
 
     if command_name not in _COMMANDS:
-        sys.stderr.write(__(f'sphinx: {command_name!r} is not a sphinx command. '
-                            "See 'sphinx --help'.\n"))
+        sys.stderr.write(
+            __(
+                f'sphinx: {command_name!r} is not a sphinx command. '
+                "See 'sphinx --help'.\n"
+            )
+        )
         raise SystemExit(2)
 
     return command_name, command_argv
diff --git a/sphinx/_cli/util/colour.py b/sphinx/_cli/util/colour.py
index a89d04ec52b..a93d7d044a1 100644
--- a/sphinx/_cli/util/colour.py
+++ b/sphinx/_cli/util/colour.py
@@ -57,6 +57,7 @@ def inner(text: str) -> str:
         if _COLOURING_DISABLED:
             return text
         return f'\x1b[{escape_code}m{text}\x1b[39;49;00m'
+
     return inner
 
 
@@ -69,11 +70,13 @@ def inner(text: str) -> str:
 if sys.platform == 'win32':
     _create_input_mode_colour_func = _create_colour_func
 else:
+
     def _create_input_mode_colour_func(escape_code: str, /) -> Callable[[str], str]:
         def inner(text: str) -> str:
             if _COLOURING_DISABLED:
                 return text
             return f'\x01\x1b[{escape_code}m\x02{text}\x01\x1b[39;49;00m\x02'
+
         return inner
 
 
diff --git a/sphinx/_cli/util/errors.py b/sphinx/_cli/util/errors.py
index dac0fb83c56..e630df22b6c 100644
--- a/sphinx/_cli/util/errors.py
+++ b/sphinx/_cli/util/errors.py
@@ -72,10 +72,15 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
     if app is not None:
         extensions = app.extensions.values()
         last_msgs = '\n'.join(f'* {strip_colors(s)}' for s in app.messagelog)
-        exts_list = '\n'.join(f'* {ext.name} ({ext.version})' for ext in extensions
-                              if ext.version != 'builtin')
-
-    with tempfile.NamedTemporaryFile(suffix='.log', prefix='sphinx-err-', delete=False) as f:
+        exts_list = '\n'.join(
+            f'* {ext.name} ({ext.version})'
+            for ext in extensions
+            if ext.version != 'builtin'
+        )
+
+    with tempfile.NamedTemporaryFile(
+        suffix='.log', prefix='sphinx-err-', delete=False
+    ) as f:
         f.write(error_info(last_msgs, exts_list, exc_format).encode('utf-8'))
 
     return f.name
@@ -143,9 +148,13 @@ def print_red(*values: str) -> None:
         print_red(__('Recursion error:'))
         print_err(str(exception))
         print_err()
-        print_err(__('This can happen with very large or deeply nested source '
-                     'files. You can carefully increase the default Python '
-                     'recursion limit of 1000 in conf.py with e.g.:'))
+        print_err(
+            __(
+                'This can happen with very large or deeply nested source '
+                'files. You can carefully increase the default Python '
+                'recursion limit of 1000 in conf.py with e.g.:'
+            )
+        )
         print_err('\n    import sys\n    sys.setrecursionlimit(1_500)\n')
         return
 
@@ -159,7 +168,15 @@ def print_red(*values: str) -> None:
     print_err(__('The full traceback has been saved in:'))
     print_err(traceback_info_path)
     print_err()
-    print_err(__('To report this error to the developers, please open an issue '
-                 'at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!'))
-    print_err(__('Please also report this if it was a user error, so '
-                 'that a better error message can be provided next time.'))
+    print_err(
+        __(
+            'To report this error to the developers, please open an issue '
+            'at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!'
+        )
+    )
+    print_err(
+        __(
+            'Please also report this if it was a user error, so '
+            'that a better error message can be provided next time.'
+        )
+    )

From b372b2f5294e18eddaafcbee578aef247b3acf48 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 15:02:41 +0100
Subject: [PATCH 19/29] Enable automatic formatting for
 ``sphinx/pygments_styles.py`` (#12963)

---
 .ruff.toml                |  1 -
 sphinx/pygments_styles.py | 98 +++++++++++++++++++--------------------
 2 files changed, 49 insertions(+), 50 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 7ab7cb70584..7efec584266 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -477,7 +477,6 @@ exclude = [
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
     "sphinx/pycode/*",
-    "sphinx/pygments_styles.py",
     "sphinx/registry.py",
     "sphinx/search/*",
     "sphinx/testing/*",
diff --git a/sphinx/pygments_styles.py b/sphinx/pygments_styles.py
index d2266421c25..55ca71b19d2 100644
--- a/sphinx/pygments_styles.py
+++ b/sphinx/pygments_styles.py
@@ -43,54 +43,54 @@ class PyramidStyle(Style):
 
     # work in progress...
 
-    background_color = "#f8f8f8"
-    default_style = ""
+    background_color = '#f8f8f8'
+    default_style = ''
 
     styles = {
-        Whitespace:                "#bbbbbb",
-        Comment:                   "italic #60a0b0",
-        Comment.Preproc:           "noitalic #007020",
-        Comment.Special:           "noitalic bg:#fff0f0",
-
-        Keyword:                   "bold #007020",
-        Keyword.Pseudo:            "nobold",
-        Keyword.Type:              "nobold #902000",
-
-        Operator:                  "#666666",
-        Operator.Word:             "bold #007020",
-
-        Name.Builtin:              "#007020",
-        Name.Function:             "#06287e",
-        Name.Class:                "bold #0e84b5",
-        Name.Namespace:            "bold #0e84b5",
-        Name.Exception:            "#007020",
-        Name.Variable:             "#bb60d5",
-        Name.Constant:             "#60add5",
-        Name.Label:                "bold #002070",
-        Name.Entity:               "bold #d55537",
-        Name.Attribute:            "#0e84b5",
-        Name.Tag:                  "bold #062873",
-        Name.Decorator:            "bold #555555",
-
-        String:                    "#4070a0",
-        String.Doc:                "italic",
-        String.Interpol:           "italic #70a0d0",
-        String.Escape:             "bold #4070a0",
-        String.Regex:              "#235388",
-        String.Symbol:             "#517918",
-        String.Other:              "#c65d09",
-        Number:                    "#40a070",
-
-        Generic.Heading:           "bold #000080",
-        Generic.Subheading:        "bold #800080",
-        Generic.Deleted:           "#A00000",
-        Generic.Inserted:          "#00A000",
-        Generic.Error:             "#FF0000",
-        Generic.Emph:              "italic",
-        Generic.Strong:            "bold",
-        Generic.Prompt:            "bold #c65d09",
-        Generic.Output:            "#888",
-        Generic.Traceback:         "#04D",
-
-        Error:                     "#a40000 bg:#fbe3e4",
-    }
+        Whitespace:         '#bbbbbb',
+        Comment:            'italic #60a0b0',
+        Comment.Preproc:    'noitalic #007020',
+        Comment.Special:    'noitalic bg:#fff0f0',
+
+        Keyword:            'bold #007020',
+        Keyword.Pseudo:     'nobold',
+        Keyword.Type:       'nobold #902000',
+
+        Operator:           '#666666',
+        Operator.Word:      'bold #007020',
+
+        Name.Builtin:       '#007020',
+        Name.Function:      '#06287e',
+        Name.Class:         'bold #0e84b5',
+        Name.Namespace:     'bold #0e84b5',
+        Name.Exception:     '#007020',
+        Name.Variable:      '#bb60d5',
+        Name.Constant:      '#60add5',
+        Name.Label:         'bold #002070',
+        Name.Entity:        'bold #d55537',
+        Name.Attribute:     '#0e84b5',
+        Name.Tag:           'bold #062873',
+        Name.Decorator:     'bold #555555',
+
+        String:             '#4070a0',
+        String.Doc:         'italic',
+        String.Interpol:    'italic #70a0d0',
+        String.Escape:      'bold #4070a0',
+        String.Regex:       '#235388',
+        String.Symbol:      '#517918',
+        String.Other:       '#c65d09',
+        Number:             '#40a070',
+
+        Generic.Heading:    'bold #000080',
+        Generic.Subheading: 'bold #800080',
+        Generic.Deleted:    '#A00000',
+        Generic.Inserted:   '#00A000',
+        Generic.Error:      '#FF0000',
+        Generic.Emph:       'italic',
+        Generic.Strong:     'bold',
+        Generic.Prompt:     'bold #c65d09',
+        Generic.Output:     '#888',
+        Generic.Traceback:  '#04D',
+
+        Error:              '#a40000 bg:#fbe3e4',
+    }  # fmt: skip

From c1d192e2c241c704af393b948434ca019ae44ee6 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 15:33:10 +0100
Subject: [PATCH 20/29] Enable automatic formatting for ``sphinx/directives/``
 (#12964)

---
 .ruff.toml                    |   1 -
 sphinx/directives/__init__.py |  45 +++++++-----
 sphinx/directives/code.py     | 133 +++++++++++++++++++++-------------
 sphinx/directives/other.py    |  56 ++++++++------
 sphinx/directives/patches.py  |  45 +++++++-----
 5 files changed, 170 insertions(+), 110 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 7efec584266..10107a583c1 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -447,7 +447,6 @@ exclude = [
     "sphinx/builders/*",
     "sphinx/cmd/*",
     "sphinx/config.py",
-    "sphinx/directives/*",
     "sphinx/domains/*",
     "sphinx/environment/*",
     "sphinx/ext/autodoc/__init__.py",
diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py
index fb42e5ee314..218bc6d5431 100644
--- a/sphinx/directives/__init__.py
+++ b/sphinx/directives/__init__.py
@@ -111,7 +111,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         raise ValueError
 
-    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: ObjDescT, sig: str, signode: desc_signature
+    ) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -228,19 +230,18 @@ def run(self) -> list[Node]:
             self.options['no-index'] = self.options['noindex']
         if 'no-index-entry' not in self.options and 'noindexentry' in self.options:
             self.options['no-index-entry'] = self.options['noindexentry']
-        if 'no-contents-entry' not in self.options and 'nocontentsentry' in self.options:
+        if (
+            'no-contents-entry' not in self.options
+            and 'nocontentsentry' in self.options
+        ):
             self.options['no-contents-entry'] = self.options['nocontentsentry']
 
-        node['no-index'] = node['noindex'] = no_index = (
-            'no-index' in self.options
-        )
-        node['no-index-entry'] = node['noindexentry'] = (
-            'no-index-entry' in self.options
-        )
+        node['no-index'] = node['noindex'] = no_index = 'no-index' in self.options
+        node['no-index-entry'] = node['noindexentry'] = 'no-index-entry' in self.options
         node['no-contents-entry'] = node['nocontentsentry'] = (
             'no-contents-entry' in self.options
         )
-        node['no-typesetting'] = ('no-typesetting' in self.options)
+        node['no-typesetting'] = 'no-typesetting' in self.options
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
@@ -287,8 +288,9 @@ def run(self) -> list[Node]:
         content_node = addnodes.desc_content('', *content_children)
         node.append(content_node)
         self.transform_content(content_node)
-        self.env.app.emit('object-description-transform',
-                          self.domain, self.objtype, content_node)
+        self.env.app.emit(
+            'object-description-transform', self.domain, self.objtype, content_node
+        )
         DocFieldTransformer(self).transform_all(content_node)
         self.env.temp_data['object'] = None
         self.after_content()
@@ -299,8 +301,11 @@ def run(self) -> list[Node]:
             # If ``:no-index:`` is set, or there are no ids on the node
             # or any of its children, then just return the index node,
             # as Docutils expects a target node to have at least one id.
-            if node_ids := [node_id for el in node.findall(nodes.Element)  # type: ignore[var-annotated]
-                            for node_id in el.get('ids', ())]:
+            if node_ids := [  # type: ignore[var-annotated]
+                node_id
+                for el in node.findall(nodes.Element)
+                for node_id in el.get('ids', ())
+            ]:
                 target_node = nodes.target(ids=node_ids)
                 self.set_source_info(target_node)
                 return [self.indexnode, target_node]
@@ -321,16 +326,20 @@ def run(self) -> list[Node]:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
-        role, messages = roles.role(role_name, self.state_machine.language,
-                                    self.lineno, self.state.reporter)
+        role, messages = roles.role(
+            role_name, self.state_machine.language, self.lineno, self.state.reporter
+        )
         if role:
             docutils.register_role('', role)  # type: ignore[arg-type]
             self.env.temp_data['default_role'] = role_name
         else:
             literal_block = nodes.literal_block(self.block_text, self.block_text)
             reporter = self.state.reporter
-            error = reporter.error('Unknown interpreted text role "%s".' % role_name,
-                                   literal_block, line=self.lineno)
+            error = reporter.error(
+                'Unknown interpreted text role "%s".' % role_name,
+                literal_block,
+                line=self.lineno,
+            )
             messages += [error]
 
         return cast(list[nodes.Node], messages)
@@ -360,7 +369,7 @@ def run(self) -> list[Node]:
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value("strip_signature_backslash", False, 'env')
+    app.add_config_value('strip_signature_backslash', False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
     directives.register_directive('describe', ObjectDescription)
diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py
index 5dc42e5b744..bb2e85316a4 100644
--- a/sphinx/directives/code.py
+++ b/sphinx/directives/code.py
@@ -45,13 +45,15 @@ def run(self) -> list[Node]:
         force = 'force' in self.options
 
         self.env.temp_data['highlight_language'] = language
-        return [addnodes.highlightlang(lang=language,
-                                       force=force,
-                                       linenothreshold=linenothreshold)]
+        return [
+            addnodes.highlightlang(
+                lang=language, force=force, linenothreshold=linenothreshold
+            )
+        ]
 
 
 def dedent_lines(
-    lines: list[str], dedent: int | None, location: tuple[str, int] | None = None,
+    lines: list[str], dedent: int | None, location: tuple[str, int] | None = None
 ) -> list[str]:
     if dedent is None:
         return textwrap.dedent(''.join(lines)).splitlines(True)
@@ -70,10 +72,11 @@ def dedent_lines(
 
 
 def container_wrapper(
-    directive: SphinxDirective, literal_node: Node, caption: str,
+    directive: SphinxDirective, literal_node: Node, caption: str
 ) -> nodes.container:
-    container_node = nodes.container('', literal_block=True,
-                                     classes=['literal-block-wrapper'])
+    container_node = nodes.container(
+        '', literal_block=True, classes=['literal-block-wrapper']
+    )
     parsed = directive.parse_text_to_nodes(caption, offset=directive.content_offset)
     node = parsed[0]
     if isinstance(node, nodes.system_message):
@@ -121,9 +124,12 @@ def run(self) -> list[Node]:
                 nlines = len(self.content)
                 hl_lines = parselinenos(linespec, nlines)
                 if any(i >= nlines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r'),
-                                   nlines, self.options['emphasize-lines'],
-                                   location=location)
+                    logger.warning(
+                        __('line number spec is out of range(1-%d): %r'),
+                        nlines,
+                        self.options['emphasize-lines'],
+                        location=location,
+                    )
 
                 hl_lines = [x + 1 for x in hl_lines if x < nlines]
             except ValueError as err:
@@ -149,8 +155,9 @@ def run(self) -> list[Node]:
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            literal['language'] = self.env.temp_data.get('highlight_language',
-                                                         self.config.highlight_language)
+            literal['language'] = self.env.temp_data.get(
+                'highlight_language', self.config.highlight_language
+            )
         extra_args = literal['highlight_args'] = {}
         if hl_lines is not None:
             extra_args['hl_lines'] = hl_lines
@@ -200,11 +207,11 @@ def __init__(self, filename: str, options: dict[str, Any], config: Config) -> No
     def parse_options(self) -> None:
         for option1, option2 in self.INVALID_OPTIONS_PAIR:
             if option1 in self.options and option2 in self.options:
-                raise ValueError(__('Cannot use both "%s" and "%s" options') %
-                                 (option1, option2))
+                msg = __('Cannot use both "%s" and "%s" options') % (option1, option2)
+                raise ValueError(msg)
 
     def read_file(
-        self, filename: str, location: tuple[str, int] | None = None,
+        self, filename: str, location: tuple[str, int] | None = None
     ) -> list[str]:
         try:
             with open(filename, encoding=self.encoding, errors='strict') as f:
@@ -214,24 +221,28 @@ def read_file(
 
                 return text.splitlines(True)
         except OSError as exc:
-            raise OSError(__('Include file %r not found or reading it failed') %
-                          filename) from exc
+            msg = __('Include file %r not found or reading it failed') % filename
+            raise OSError(msg) from exc
         except UnicodeError as exc:
-            raise UnicodeError(__('Encoding %r used for reading included file %r seems to '
-                                  'be wrong, try giving an :encoding: option') %
-                               (self.encoding, filename)) from exc
+            msg = __(
+                'Encoding %r used for reading included file %r seems to '
+                'be wrong, try giving an :encoding: option'
+            ) % (self.encoding, filename)
+            raise UnicodeError(msg) from exc
 
     def read(self, location: tuple[str, int] | None = None) -> tuple[str, int]:
         if 'diff' in self.options:
             lines = self.show_diff()
         else:
-            filters = [self.pyobject_filter,
-                       self.start_filter,
-                       self.end_filter,
-                       self.lines_filter,
-                       self.dedent_filter,
-                       self.prepend_filter,
-                       self.append_filter]
+            filters = [
+                self.pyobject_filter,
+                self.start_filter,
+                self.end_filter,
+                self.lines_filter,
+                self.dedent_filter,
+                self.prepend_filter,
+                self.append_filter,
+            ]
             lines = self.read_file(self.filename, location=location)
             for func in filters:
                 lines = func(lines, location=location)
@@ -246,33 +257,41 @@ def show_diff(self, location: tuple[str, int] | None = None) -> list[str]:
         return list(diff)
 
     def pyobject_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         pyobject = self.options.get('pyobject')
         if pyobject:
             from sphinx.pycode import ModuleAnalyzer
+
             analyzer = ModuleAnalyzer.for_file(self.filename, '')
             tags = analyzer.find_tags()
             if pyobject not in tags:
-                raise ValueError(__('Object named %r not found in include file %r') %
-                                 (pyobject, self.filename))
+                msg = __('Object named %r not found in include file %r') % (
+                    pyobject,
+                    self.filename,
+                )
+                raise ValueError(msg)
             start = tags[pyobject][1]
             end = tags[pyobject][2]
-            lines = lines[start - 1:end]
+            lines = lines[start - 1 : end]
             if 'lineno-match' in self.options:
                 self.lineno_start = start
 
         return lines
 
     def lines_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         linespec = self.options.get('lines')
         if linespec:
             linelist = parselinenos(linespec, len(lines))
             if any(i >= len(lines) for i in linelist):
-                logger.warning(__('line number spec is out of range(1-%d): %r'),
-                               len(lines), linespec, location=location)
+                logger.warning(
+                    __('line number spec is out of range(1-%d): %r'),
+                    len(lines),
+                    linespec,
+                    location=location,
+                )
 
             if 'lineno-match' in self.options:
                 # make sure the line list is not "disjoint".
@@ -280,18 +299,21 @@ def lines_filter(
                 if all(first + i == n for i, n in enumerate(linelist)):
                     self.lineno_start += linelist[0]
                 else:
-                    raise ValueError(__('Cannot use "lineno-match" with a disjoint '
-                                        'set of "lines"'))
+                    msg = __('Cannot use "lineno-match" with a disjoint set of "lines"')
+                    raise ValueError(msg)
 
             lines = [lines[n] for n in linelist if n < len(lines)]
             if not lines:
-                raise ValueError(__('Line spec %r: no lines pulled from include file %r') %
-                                 (linespec, self.filename))
+                msg = __('Line spec %r: no lines pulled from include file %r') % (
+                    linespec,
+                    self.filename,
+                )
+                raise ValueError(msg)
 
         return lines
 
     def start_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'start-at' in self.options:
             start = self.options.get('start-at')
@@ -309,7 +331,7 @@ def start_filter(
                         if 'lineno-match' in self.options:
                             self.lineno_start += lineno + 1
 
-                        return lines[lineno + 1:]
+                        return lines[lineno + 1 :]
                     else:
                         if 'lineno-match' in self.options:
                             self.lineno_start += lineno
@@ -324,7 +346,7 @@ def start_filter(
         return lines
 
     def end_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'end-at' in self.options:
             end = self.options.get('end-at')
@@ -339,7 +361,7 @@ def end_filter(
             for lineno, line in enumerate(lines):
                 if end in line:
                     if inclusive:
-                        return lines[:lineno + 1]
+                        return lines[: lineno + 1]
                     else:
                         if lineno == 0:
                             pass  # end-before ignores first line
@@ -353,7 +375,7 @@ def end_filter(
         return lines
 
     def prepend_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         prepend = self.options.get('prepend')
         if prepend:
@@ -362,7 +384,7 @@ def prepend_filter(
         return lines
 
     def append_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         append = self.options.get('append')
         if append:
@@ -371,7 +393,7 @@ def append_filter(
         return lines
 
     def dedent_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'dedent' in self.options:
             return dedent_lines(lines, self.options.get('dedent'), location=location)
@@ -417,8 +439,9 @@ class LiteralInclude(SphinxDirective):
     def run(self) -> list[Node]:
         document = self.state.document
         if not document.settings.file_insertion_enabled:
-            return [document.reporter.warning('File insertion disabled',
-                                              line=self.lineno)]
+            return [
+                document.reporter.warning('File insertion disabled', line=self.lineno)
+            ]
         # convert options['diff'] to absolute path
         if 'diff' in self.options:
             _, path = self.env.relfn2path(self.options['diff'])
@@ -439,17 +462,23 @@ def run(self) -> list[Node]:
                 retnode['language'] = 'udiff'
             elif 'language' in self.options:
                 retnode['language'] = self.options['language']
-            if ('linenos' in self.options or 'lineno-start' in self.options or
-                    'lineno-match' in self.options):
+            if (
+                'linenos' in self.options
+                or 'lineno-start' in self.options
+                or 'lineno-match' in self.options
+            ):
                 retnode['linenos'] = True
             retnode['classes'] += self.options.get('class', [])
             extra_args = retnode['highlight_args'] = {}
             if 'emphasize-lines' in self.options:
                 hl_lines = parselinenos(self.options['emphasize-lines'], lines)
                 if any(i >= lines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r'),
-                                   lines, self.options['emphasize-lines'],
-                                   location=location)
+                    logger.warning(
+                        __('line number spec is out of range(1-%d): %r'),
+                        lines,
+                        self.options['emphasize-lines'],
+                        location=location,
+                    )
                 extra_args['hl_lines'] = [x + 1 for x in hl_lines if x < lines]
             extra_args['linenostart'] = reader.lineno_start
 
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 18fdff194ee..d0947470fc7 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -112,14 +112,17 @@ def parse_content(self, toctree: addnodes.toctree) -> None:
             if glob and glob_re.match(entry) and not explicit and not url_match:
                 pat_name = docname_join(current_docname, entry)
                 doc_names = sorted(
-                    docname for docname in patfilter(all_docnames, pat_name)
+                    docname
+                    for docname in patfilter(all_docnames, pat_name)
                     # don't include generated documents in globs
                     if docname not in generated_docnames
                 )
                 if not doc_names:
                     logger.warning(
                         __("toctree glob pattern %r didn't match any documents"),
-                        entry, location=toctree)
+                        entry,
+                        location=toctree,
+                    )
 
                 for docname in doc_names:
                     all_docnames.remove(docname)  # don't include it again
@@ -149,22 +152,26 @@ def parse_content(self, toctree: addnodes.toctree) -> None:
 
             if docname not in frozen_all_docnames:
                 if excluded(str(self.env.doc2path(docname, False))):
-                    message = __('toctree contains reference to excluded document %r')
+                    msg = __('toctree contains reference to excluded document %r')
                     subtype = 'excluded'
                 else:
-                    message = __('toctree contains reference to nonexisting document %r')
+                    msg = __('toctree contains reference to nonexisting document %r')
                     subtype = 'not_readable'
 
-                logger.warning(message, docname, type='toc', subtype=subtype,
-                               location=toctree)
+                logger.warning(
+                    msg, docname, type='toc', subtype=subtype, location=toctree
+                )
                 self.env.note_reread()
                 continue
 
             if docname in all_docnames:
                 all_docnames.remove(docname)
             else:
-                logger.warning(__('duplicated entry found in toctree: %s'), docname,
-                               location=toctree)
+                logger.warning(
+                    __('duplicated entry found in toctree: %s'),
+                    docname,
+                    location=toctree,
+                )
 
             toctree['entries'].append((title, docname))
             toctree['includefiles'].append(docname)
@@ -273,8 +280,10 @@ class Acks(SphinxDirective):
     def run(self) -> list[Node]:
         children = self.parse_content_to_nodes()
         if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
-            logger.warning(__('.. acks content is not a list'),
-                           location=(self.env.docname, self.lineno))
+            logger.warning(
+                __('.. acks content is not a list'),
+                location=(self.env.docname, self.lineno),
+            )
             return []
         return [addnodes.acks('', *children)]
 
@@ -296,8 +305,10 @@ def run(self) -> list[Node]:
         ncolumns = self.options.get('columns', 2)
         children = self.parse_content_to_nodes()
         if len(children) != 1 or not isinstance(children[0], nodes.bullet_list):
-            logger.warning(__('.. hlist content is not a list'),
-                           location=(self.env.docname, self.lineno))
+            logger.warning(
+                __('.. hlist content is not a list'),
+                location=(self.env.docname, self.lineno),
+            )
             return []
         fulllist = children[0]
         # create a hlist node where the items are distributed
@@ -339,13 +350,16 @@ def run(self) -> list[Node]:
         memo.title_styles = []
         memo.section_level = 0
         try:
-            self.state.nested_parse(self.content, self.content_offset,
-                                    node, match_titles=True)
+            self.state.nested_parse(
+                self.content, self.content_offset, node, match_titles=True
+            )
             title_styles = memo.title_styles
-            if (not surrounding_title_styles or
-                    not title_styles or
-                    title_styles[0] not in surrounding_title_styles or
-                    not self.state.parent):
+            if (
+                not surrounding_title_styles
+                or not title_styles
+                or title_styles[0] not in surrounding_title_styles
+                or not self.state.parent
+            ):
                 # No nested sections so no special handling needed.
                 return [node]
             # Calculate the depths of the current and nested sections.
@@ -380,7 +394,6 @@ class Include(BaseInclude, SphinxDirective):
     """
 
     def run(self) -> Sequence[Node]:
-
         # To properly emit "include-read" events from included RST text,
         # we must patch the ``StateMachine.insert_input()`` method.
         # In the future, docutils will hopefully offer a way for Sphinx
@@ -392,7 +405,7 @@ def _insert_input(include_lines: list[str], source: str) -> None:
             # In docutils 0.18 and later, there are two lines at the end
             # that act as markers.
             # We must preserve them and leave them out of the include-read event:
-            text = "\n".join(include_lines[:-2])
+            text = '\n'.join(include_lines[:-2])
 
             path = Path(relpath(abspath(source), start=self.env.srcdir))
             docname = self.env.docname
@@ -415,8 +428,7 @@ def _insert_input(include_lines: list[str], source: str) -> None:
             # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
             self.state_machine.insert_input = _insert_input
 
-        if self.arguments[0].startswith('<') and \
-           self.arguments[0].endswith('>'):
+        if self.arguments[0].startswith('<') and self.arguments[0].endswith('>'):
             # docutils "standard" includes, do not do path processing
             return super().run()
         rel_filename, filename = self.env.relfn2path(self.arguments[0])
diff --git a/sphinx/directives/patches.py b/sphinx/directives/patches.py
index 0dd6dc82a30..3503f2e3411 100644
--- a/sphinx/directives/patches.py
+++ b/sphinx/directives/patches.py
@@ -62,10 +62,14 @@ def run(self) -> list[Node]:
             env = self.state.document.settings.env
             filename = self.options['file']
             if path.exists(filename):
-                logger.warning(__('":file:" option for csv-table directive now recognizes '
-                                  'an absolute path as a relative path from source directory. '
-                                  'Please update your document.'),
-                               location=(env.docname, self.lineno))
+                logger.warning(
+                    __(
+                        '":file:" option for csv-table directive now recognizes '
+                        'an absolute path as a relative path from source directory. '
+                        'Please update your document.'
+                    ),
+                    location=(env.docname, self.lineno),
+                )
             else:
                 abspath = path.join(env.srcdir, os_path(self.options['file'][1:]))
                 docdir = path.dirname(env.doc2path(env.docname))
@@ -94,10 +98,13 @@ def run(self) -> list[Node]:
 
         set_classes(self.options)
         code = '\n'.join(self.content)
-        node = nodes.literal_block(code, code,
-                                   classes=self.options.get('classes', []),
-                                   force='force' in self.options,
-                                   highlight_args={})
+        node = nodes.literal_block(
+            code,
+            code,
+            classes=self.options.get('classes', []),
+            force='force' in self.options,
+            highlight_args={},
+        )
         self.add_name(node)
         set_source_info(self, node)
 
@@ -108,8 +115,9 @@ def run(self) -> list[Node]:
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            node['language'] = self.env.temp_data.get('highlight_language',
-                                                      self.config.highlight_language)
+            node['language'] = self.env.temp_data.get(
+                'highlight_language', self.config.highlight_language
+            )
 
         if 'number-lines' in self.options:
             node['linenos'] = True
@@ -138,12 +146,15 @@ def run(self) -> list[Node]:
         if self.arguments and self.arguments[0]:
             latex = self.arguments[0] + '\n\n' + latex
         label = self.options.get('label', self.options.get('name'))
-        node = nodes.math_block(latex, latex,
-                                classes=self.options.get('class', []),
-                                docname=self.env.docname,
-                                number=None,
-                                label=label,
-                                nowrap='nowrap' in self.options)
+        node = nodes.math_block(
+            latex,
+            latex,
+            classes=self.options.get('class', []),
+            docname=self.env.docname,
+            number=None,
+            label=label,
+            nowrap='nowrap' in self.options,
+        )
         self.add_name(node)
         self.set_source_info(node)
 
@@ -157,7 +168,7 @@ def add_target(self, ret: list[Node]) -> None:
         # assign label automatically if math_number_all enabled
         if node['label'] == '' or (self.config.math_number_all and not node['label']):
             seq = self.env.new_serialno('sphinx.ext.math#equations')
-            node['label'] = "%s:%d" % (self.env.docname, seq)
+            node['label'] = f'{self.env.docname}:{seq}'
 
         # no targets and numbers are needed
         if not node['label']:

From a44293a3a8c338ad3b38c6b9b06ae643450e0fda Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 15:33:19 +0100
Subject: [PATCH 21/29] Enable automatic formatting for ``sphinx/pycode/``
 (#12965)

---
 .ruff.toml                |   1 -
 sphinx/pycode/__init__.py |  15 +++--
 sphinx/pycode/ast.py      | 116 +++++++++++++++++++-------------------
 sphinx/pycode/parser.py   |  77 ++++++++++++++++---------
 4 files changed, 118 insertions(+), 91 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 10107a583c1..629cee4280f 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -475,7 +475,6 @@ exclude = [
     "sphinx/ext/napoleon/docstring.py",
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
-    "sphinx/pycode/*",
     "sphinx/registry.py",
     "sphinx/search/*",
     "sphinx/testing/*",
diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py
index 92de047c569..da078b2f0f0 100644
--- a/sphinx/pycode/__init__.py
+++ b/sphinx/pycode/__init__.py
@@ -52,7 +52,9 @@ def get_module_source(modname: str) -> tuple[str | None, str | None]:
             try:
                 filename = loader.get_filename(modname)
             except ImportError as err:
-                raise PycodeError('error getting filename for %r' % modname, err) from err
+                raise PycodeError(
+                    'error getting filename for %r' % modname, err
+                ) from err
         if filename is None:
             # all methods for getting filename failed, so raise...
             raise PycodeError('no source found for module %r' % modname)
@@ -70,12 +72,17 @@ def get_module_source(modname: str) -> tuple[str | None, str | None]:
 
     @classmethod
     def for_string(
-        cls: type[ModuleAnalyzer], string: str, modname: str, srcname: str = '<string>',
+        cls: type[ModuleAnalyzer],
+        string: str,
+        modname: str,
+        srcname: str = '<string>',
     ) -> ModuleAnalyzer:
         return cls(string, modname, srcname)
 
     @classmethod
-    def for_file(cls: type[ModuleAnalyzer], filename: str, modname: str) -> ModuleAnalyzer:
+    def for_file(
+        cls: type[ModuleAnalyzer], filename: str, modname: str
+    ) -> ModuleAnalyzer:
         if ('file', filename) in cls.cache:
             return cls.cache['file', filename]
         try:
@@ -126,7 +133,7 @@ def analyze(self) -> None:
             parser.parse()
 
             self.attr_docs = {}
-            for (scope, comment) in parser.comments.items():
+            for scope, comment in parser.comments.items():
                 if comment:
                     self.attr_docs[scope] = [*comment.splitlines(), '']
                 else:
diff --git a/sphinx/pycode/ast.py b/sphinx/pycode/ast.py
index 7ed107f4ab3..f6bcbda9759 100644
--- a/sphinx/pycode/ast.py
+++ b/sphinx/pycode/ast.py
@@ -6,36 +6,34 @@
 from typing import NoReturn, overload
 
 OPERATORS: dict[type[ast.AST], str] = {
-    ast.Add: "+",
-    ast.And: "and",
-    ast.BitAnd: "&",
-    ast.BitOr: "|",
-    ast.BitXor: "^",
-    ast.Div: "/",
-    ast.FloorDiv: "//",
-    ast.Invert: "~",
-    ast.LShift: "<<",
-    ast.MatMult: "@",
-    ast.Mult: "*",
-    ast.Mod: "%",
-    ast.Not: "not",
-    ast.Pow: "**",
-    ast.Or: "or",
-    ast.RShift: ">>",
-    ast.Sub: "-",
-    ast.UAdd: "+",
-    ast.USub: "-",
+    ast.Add: '+',
+    ast.And: 'and',
+    ast.BitAnd: '&',
+    ast.BitOr: '|',
+    ast.BitXor: '^',
+    ast.Div: '/',
+    ast.FloorDiv: '//',
+    ast.Invert: '~',
+    ast.LShift: '<<',
+    ast.MatMult: '@',
+    ast.Mult: '*',
+    ast.Mod: '%',
+    ast.Not: 'not',
+    ast.Pow: '**',
+    ast.Or: 'or',
+    ast.RShift: '>>',
+    ast.Sub: '-',
+    ast.UAdd: '+',
+    ast.USub: '-',
 }
 
 
 @overload
-def unparse(node: None, code: str = '') -> None:
-    ...
+def unparse(node: None, code: str = '') -> None: ...  # NoQA: E704
 
 
 @overload
-def unparse(node: ast.AST, code: str = '') -> str:
-    ...
+def unparse(node: ast.AST, code: str = '') -> str: ...  # NoQA: E704
 
 
 def unparse(node: ast.AST | None, code: str = '') -> str | None:
@@ -54,12 +52,13 @@ def __init__(self, code: str = '') -> None:
 
     def _visit_op(self, node: ast.AST) -> str:
         return OPERATORS[node.__class__]
+
     for _op in OPERATORS:
         locals()[f'visit_{_op.__name__}'] = _visit_op
 
     def visit_arg(self, node: ast.arg) -> str:
         if node.annotation:
-            return f"{node.arg}: {self.visit(node.annotation)}"
+            return f'{node.arg}: {self.visit(node.annotation)}'
         else:
             return node.arg
 
@@ -68,9 +67,9 @@ def _visit_arg_with_default(self, arg: ast.arg, default: ast.AST | None) -> str:
         name = self.visit(arg)
         if default:
             if arg.annotation:
-                name += " = %s" % self.visit(default)
+                name += ' = %s' % self.visit(default)
             else:
-                name += "=%s" % self.visit(default)
+                name += '=%s' % self.visit(default)
         return name
 
     def visit_arguments(self, node: ast.arguments) -> str:
@@ -85,8 +84,10 @@ def visit_arguments(self, node: ast.arguments) -> str:
         for _ in range(len(kw_defaults), len(node.kwonlyargs)):
             kw_defaults.insert(0, None)
 
-        args: list[str] = [self._visit_arg_with_default(arg, defaults[i])
-                           for i, arg in enumerate(node.posonlyargs)]
+        args: list[str] = [
+            self._visit_arg_with_default(arg, defaults[i])
+            for i, arg in enumerate(node.posonlyargs)
+        ]
 
         if node.posonlyargs:
             args.append('/')
@@ -95,7 +96,7 @@ def visit_arguments(self, node: ast.arguments) -> str:
             args.append(self._visit_arg_with_default(arg, defaults[i + posonlyargs]))
 
         if node.vararg:
-            args.append("*" + self.visit(node.vararg))
+            args.append('*' + self.visit(node.vararg))
 
         if node.kwonlyargs and not node.vararg:
             args.append('*')
@@ -103,33 +104,33 @@ def visit_arguments(self, node: ast.arguments) -> str:
             args.append(self._visit_arg_with_default(arg, kw_defaults[i]))
 
         if node.kwarg:
-            args.append("**" + self.visit(node.kwarg))
+            args.append('**' + self.visit(node.kwarg))
 
-        return ", ".join(args)
+        return ', '.join(args)
 
     def visit_Attribute(self, node: ast.Attribute) -> str:
-        return f"{self.visit(node.value)}.{node.attr}"
+        return f'{self.visit(node.value)}.{node.attr}'
 
     def visit_BinOp(self, node: ast.BinOp) -> str:
         # Special case ``**`` to not have surrounding spaces.
         if isinstance(node.op, ast.Pow):
-            return "".join(map(self.visit, (node.left, node.op, node.right)))
-        return " ".join(map(self.visit, (node.left, node.op, node.right)))
+            return ''.join(map(self.visit, (node.left, node.op, node.right)))
+        return ' '.join(map(self.visit, (node.left, node.op, node.right)))
 
     def visit_BoolOp(self, node: ast.BoolOp) -> str:
-        op = " %s " % self.visit(node.op)
+        op = ' %s ' % self.visit(node.op)
         return op.join(self.visit(e) for e in node.values)
 
     def visit_Call(self, node: ast.Call) -> str:
         args = ', '.join(
             [self.visit(e) for e in node.args]
-            + [f"{k.arg}={self.visit(k.value)}" for k in node.keywords],
+            + [f'{k.arg}={self.visit(k.value)}' for k in node.keywords],
         )
-        return f"{self.visit(node.func)}({args})"
+        return f'{self.visit(node.func)}({args})'
 
     def visit_Constant(self, node: ast.Constant) -> str:
         if node.value is Ellipsis:
-            return "..."
+            return '...'
         elif isinstance(node.value, int | float | complex):
             if self.code:
                 return ast.get_source_segment(self.code, node) or repr(node.value)
@@ -141,34 +142,34 @@ def visit_Constant(self, node: ast.Constant) -> str:
     def visit_Dict(self, node: ast.Dict) -> str:
         keys = (self.visit(k) for k in node.keys if k is not None)
         values = (self.visit(v) for v in node.values)
-        items = (k + ": " + v for k, v in zip(keys, values, strict=True))
-        return "{" + ", ".join(items) + "}"
+        items = (k + ': ' + v for k, v in zip(keys, values, strict=True))
+        return '{' + ', '.join(items) + '}'
 
     def visit_Lambda(self, node: ast.Lambda) -> str:
-        return "lambda %s: ..." % self.visit(node.args)
+        return 'lambda %s: ...' % self.visit(node.args)
 
     def visit_List(self, node: ast.List) -> str:
-        return "[" + ", ".join(self.visit(e) for e in node.elts) + "]"
+        return '[' + ', '.join(self.visit(e) for e in node.elts) + ']'
 
     def visit_Name(self, node: ast.Name) -> str:
         return node.id
 
     def visit_Set(self, node: ast.Set) -> str:
-        return "{" + ", ".join(self.visit(e) for e in node.elts) + "}"
+        return '{' + ', '.join(self.visit(e) for e in node.elts) + '}'
 
     def visit_Slice(self, node: ast.Slice) -> str:
         if not node.lower and not node.upper and not node.step:
             # Empty slice with default values -> [:]
-            return ":"
+            return ':'
 
-        start = self.visit(node.lower) if node.lower else ""
-        stop = self.visit(node.upper) if node.upper else ""
+        start = self.visit(node.lower) if node.lower else ''
+        stop = self.visit(node.upper) if node.upper else ''
         if not node.step:
             # Default step size -> [start:stop]
-            return f"{start}:{stop}"
+            return f'{start}:{stop}'
 
-        step = self.visit(node.step) if node.step else ""
-        return f"{start}:{stop}:{step}"
+        step = self.visit(node.step) if node.step else ''
+        return f'{start}:{stop}:{step}'
 
     def visit_Subscript(self, node: ast.Subscript) -> str:
         def is_simple_tuple(value: ast.expr) -> bool:
@@ -179,25 +180,24 @@ def is_simple_tuple(value: ast.expr) -> bool:
             )
 
         if is_simple_tuple(node.slice):
-            elts = ", ".join(self.visit(e)
-                             for e in node.slice.elts)  # type: ignore[attr-defined]
-            return f"{self.visit(node.value)}[{elts}]"
-        return f"{self.visit(node.value)}[{self.visit(node.slice)}]"
+            elts = ', '.join(self.visit(e) for e in node.slice.elts)  # type: ignore[attr-defined]
+            return f'{self.visit(node.value)}[{elts}]'
+        return f'{self.visit(node.value)}[{self.visit(node.slice)}]'
 
     def visit_UnaryOp(self, node: ast.UnaryOp) -> str:
         # UnaryOp is one of {UAdd, USub, Invert, Not}, which refer to ``+x``,
         # ``-x``, ``~x``, and ``not x``. Only Not needs a space.
         if isinstance(node.op, ast.Not):
-            return f"{self.visit(node.op)} {self.visit(node.operand)}"
-        return f"{self.visit(node.op)}{self.visit(node.operand)}"
+            return f'{self.visit(node.op)} {self.visit(node.operand)}'
+        return f'{self.visit(node.op)}{self.visit(node.operand)}'
 
     def visit_Tuple(self, node: ast.Tuple) -> str:
         if len(node.elts) == 0:
-            return "()"
+            return '()'
         elif len(node.elts) == 1:
-            return "(%s,)" % self.visit(node.elts[0])
+            return '(%s,)' % self.visit(node.elts[0])
         else:
-            return "(" + ", ".join(self.visit(e) for e in node.elts) + ")"
+            return '(' + ', '.join(self.visit(e) for e in node.elts) + ')'
 
     def generic_visit(self, node: ast.AST) -> NoReturn:
         raise NotImplementedError('Unable to parse %s object' % type(node).__name__)
diff --git a/sphinx/pycode/parser.py b/sphinx/pycode/parser.py
index 18bb993053b..47ce2da1a57 100644
--- a/sphinx/pycode/parser.py
+++ b/sphinx/pycode/parser.py
@@ -63,11 +63,12 @@ def get_lvar_names(node: ast.AST, self: ast.arg | None = None) -> list[str]:
         return members
     elif node_name == 'Attribute':
         if (
-            node.value.__class__.__name__ == 'Name' and  # type: ignore[attr-defined]
-            self and node.value.id == self_id  # type: ignore[attr-defined]
+            node.value.__class__.__name__ == 'Name'  # type: ignore[attr-defined]
+            and self
+            and node.value.id == self_id  # type: ignore[attr-defined]
         ):
             # instance variable
-            return ["%s" % get_lvar_names(node.attr, self)[0]]  # type: ignore[attr-defined]
+            return ['%s' % get_lvar_names(node.attr, self)[0]]  # type: ignore[attr-defined]
         else:
             raise TypeError('The assignment %r is not instance variable' % node)
     elif node_name == 'str':
@@ -80,6 +81,7 @@ def get_lvar_names(node: ast.AST, self: ast.arg | None = None) -> list[str]:
 
 def dedent_docstring(s: str) -> str:
     """Remove common leading indentation from docstring."""
+
     def dummy() -> None:
         # dummy function to mock `inspect.getdoc`.
         pass
@@ -87,16 +89,22 @@ def dummy() -> None:
     dummy.__doc__ = s
     docstring = inspect.getdoc(dummy)
     if docstring:
-        return docstring.lstrip("\r\n").rstrip("\r\n")
+        return docstring.lstrip('\r\n').rstrip('\r\n')
     else:
-        return ""
+        return ''
 
 
 class Token:
     """Better token wrapper for tokenize module."""
 
-    def __init__(self, kind: int, value: Any, start: tuple[int, int], end: tuple[int, int],
-                 source: str) -> None:
+    def __init__(
+        self,
+        kind: int,
+        value: Any,
+        start: tuple[int, int],
+        end: tuple[int, int],
+        source: str,
+    ) -> None:
         self.kind = kind
         self.value = value
         self.start = start
@@ -201,7 +209,9 @@ def fetch_rvalue(self) -> list[Token]:
     def parse(self) -> None:
         """Parse the code and obtain comment after assignment."""
         # skip lvalue (or whole of AnnAssign)
-        while (tok := self.fetch_token()) and not tok.match([OP, '='], NEWLINE, COMMENT):
+        while (tok := self.fetch_token()) and not tok.match(
+            [OP, '='], NEWLINE, COMMENT
+        ):
             assert tok
         assert tok is not None
 
@@ -239,7 +249,7 @@ def __init__(self, buffers: list[str], encoding: str) -> None:
     def get_qualname_for(self, name: str) -> list[str] | None:
         """Get qualified name for given object as a list of string(s)."""
         if self.current_function:
-            if self.current_classes and self.context[-1] == "__init__":
+            if self.current_classes and self.context[-1] == '__init__':
                 # store variable comments inside __init__ method of classes
                 return self.context[:-1] + [name]
             else:
@@ -250,31 +260,32 @@ def get_qualname_for(self, name: str) -> list[str] | None:
     def add_entry(self, name: str) -> None:
         qualname = self.get_qualname_for(name)
         if qualname:
-            self.deforders[".".join(qualname)] = next(self.counter)
+            self.deforders['.'.join(qualname)] = next(self.counter)
 
     def add_final_entry(self, name: str) -> None:
         qualname = self.get_qualname_for(name)
         if qualname:
-            self.finals.append(".".join(qualname))
+            self.finals.append('.'.join(qualname))
 
     def add_overload_entry(self, func: ast.FunctionDef) -> None:
         # avoid circular import problem
         from sphinx.util.inspect import signature_from_ast
+
         qualname = self.get_qualname_for(func.name)
         if qualname:
-            overloads = self.overloads.setdefault(".".join(qualname), [])
+            overloads = self.overloads.setdefault('.'.join(qualname), [])
             overloads.append(signature_from_ast(func))
 
     def add_variable_comment(self, name: str, comment: str) -> None:
         qualname = self.get_qualname_for(name)
         if qualname:
-            basename = ".".join(qualname[:-1])
+            basename = '.'.join(qualname[:-1])
             self.comments[(basename, name)] = comment
 
     def add_variable_annotation(self, name: str, annotation: ast.AST) -> None:
         qualname = self.get_qualname_for(name)
         if qualname:
-            basename = ".".join(qualname[:-1])
+            basename = '.'.join(qualname[:-1])
             self.annotations[(basename, name)] = ast_unparse(annotation)
 
     def is_final(self, decorators: list[ast.expr]) -> bool:
@@ -353,7 +364,10 @@ def visit_Assign(self, node: ast.Assign) -> None:
         try:
             targets = get_assign_targets(node)
             varnames: list[str] = functools.reduce(
-                operator.iadd, [get_lvar_names(t, self=self.get_self()) for t in targets], [])
+                operator.iadd,
+                [get_lvar_names(t, self=self.get_self()) for t in targets],
+                [],
+            )
             current_line = self.get_line(node.lineno)
         except TypeError:
             return  # this assignment is not new definition!
@@ -364,21 +378,23 @@ def visit_Assign(self, node: ast.Assign) -> None:
                 self.add_variable_annotation(varname, node.annotation)
         elif hasattr(node, 'type_comment') and node.type_comment:
             for varname in varnames:
-                self.add_variable_annotation(
-                    varname, node.type_comment)  # type: ignore[arg-type]
+                self.add_variable_annotation(varname, node.type_comment)  # type: ignore[arg-type]
 
         # check comments after assignment
-        parser = AfterCommentParser([current_line[node.col_offset:]] +
-                                    self.buffers[node.lineno:])
+        parser = AfterCommentParser(
+            [current_line[node.col_offset :]] + self.buffers[node.lineno :]
+        )
         parser.parse()
         if parser.comment and comment_re.match(parser.comment):
             for varname in varnames:
-                self.add_variable_comment(varname, comment_re.sub('\\1', parser.comment))
+                self.add_variable_comment(
+                    varname, comment_re.sub('\\1', parser.comment)
+                )
                 self.add_entry(varname)
             return
 
         # check comments before assignment
-        if indent_re.match(current_line[:node.col_offset]):
+        if indent_re.match(current_line[: node.col_offset]):
             comment_lines = []
             for i in range(node.lineno - 1):
                 before_line = self.get_line(node.lineno - 1 - i)
@@ -404,8 +420,11 @@ def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
 
     def visit_Expr(self, node: ast.Expr) -> None:
         """Handles Expr node and pick up a comment if string."""
-        if (isinstance(self.previous, ast.Assign | ast.AnnAssign) and
-                isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)):
+        if (
+            isinstance(self.previous, ast.Assign | ast.AnnAssign)
+            and isinstance(node.value, ast.Constant)
+            and isinstance(node.value.value, str)
+        ):
             try:
                 targets = get_assign_targets(self.previous)
                 varnames = get_lvar_names(targets[0], self.get_self())
@@ -446,7 +465,8 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         """Handles FunctionDef node and set context."""
         if self.current_function is None:
-            self.add_entry(node.name)  # should be called before setting self.current_function
+            # should be called before setting self.current_function
+            self.add_entry(node.name)
             if self.is_final(node.decorator_list):
                 self.add_final_entry(node.name)
             if self.is_overload(node.decorator_list):
@@ -491,8 +511,10 @@ def parse(self) -> None:
                 break
             if token == COMMENT:
                 pass
-            elif token == [OP, '@'] and (self.previous is None or
-                                         self.previous.match(NEWLINE, NL, INDENT, DEDENT)):
+            elif token == [OP, '@'] and (
+                self.previous is None
+                or self.previous.match(NEWLINE, NL, INDENT, DEDENT)
+            ):
                 if self.decorator is None:
                     self.decorator = token
             elif token.match([NAME, 'class']):
@@ -522,8 +544,7 @@ def parse_definition(self, typ: str) -> None:
             self.indents.append((typ, funcname, start_pos))
         else:
             # one-liner
-            self.add_definition(funcname,
-                                (typ, start_pos, name.end[0]))  # type: ignore[union-attr]
+            self.add_definition(funcname, (typ, start_pos, name.end[0]))  # type: ignore[union-attr]
             self.context.pop()
 
     def finalize_block(self) -> None:

From dd17d4faa5baec95efd0ce2b6a8077eca77ae65f Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 15:41:25 +0100
Subject: [PATCH 22/29] Bump types-docutils to 0.21.0.20241004 (#12960)

---
 pyproject.toml                   | 2 +-
 sphinx/directives/other.py       | 2 +-
 sphinx/ext/todo.py               | 2 +-
 sphinx/io.py                     | 2 +-
 sphinx/writers/latex.py          | 7 ++++---
 sphinx/writers/texinfo.py        | 9 +++++----
 sphinx/writers/text.py           | 7 ++++---
 tests/test_markup/test_markup.py | 3 ++-
 8 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index aa650803a97..804f81290e1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -86,7 +86,7 @@ lint = [
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
     "types-defusedxml==0.7.0.20240218",
-    "types-docutils==0.21.0.20240724",
+    "types-docutils==0.21.0.20241004",
     "types-Pillow==10.2.0.20240822",
     "types-Pygments==2.18.0.20240506",
     "types-requests==2.32.0.20240914",  # align with requests
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index d0947470fc7..e297ceb4b89 100644
--- a/sphinx/directives/other.py
+++ b/sphinx/directives/other.py
@@ -217,7 +217,7 @@ def run(self) -> list[Node]:
         return ret
 
 
-class SeeAlso(BaseAdmonition):  # type: ignore[misc]
+class SeeAlso(BaseAdmonition):
     """
     An admonition mentioning things to look at as reference.
     """
diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py
index 0945731702a..836dc8b864c 100644
--- a/sphinx/ext/todo.py
+++ b/sphinx/ext/todo.py
@@ -45,7 +45,7 @@ class todolist(nodes.General, nodes.Element):
     pass
 
 
-class Todo(BaseAdmonition, SphinxDirective):  # type: ignore[misc]
+class Todo(BaseAdmonition, SphinxDirective):
     """
     A todo entry, displayed (if configured) in the form of an admonition.
     """
diff --git a/sphinx/io.py b/sphinx/io.py
index 31d64ca6d9d..7da15e1ca6a 100644
--- a/sphinx/io.py
+++ b/sphinx/io.py
@@ -143,7 +143,7 @@ def setup(self, app: Sphinx) -> None:
                 self.transforms.remove(transform)
 
 
-class SphinxDummyWriter(UnfilteredWriter):  # type: ignore[misc]
+class SphinxDummyWriter(UnfilteredWriter):  # type: ignore[type-arg]
     """Dummy writer module used for generating doctree."""
 
     supported = ('html',)  # needed to keep "meta" nodes
diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
index 44c1398206f..e8f4560a264 100644
--- a/sphinx/writers/latex.py
+++ b/sphinx/writers/latex.py
@@ -10,7 +10,7 @@
 from collections import defaultdict
 from collections.abc import Iterable
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
 
@@ -65,7 +65,7 @@ class UnsupportedError(SphinxError):
     category = 'Markup is unsupported in LaTeX'
 
 
-class LaTeXWriter(writers.Writer):  # type: ignore[misc]
+class LaTeXWriter(writers.Writer):  # type: ignore[type-arg]
 
     supported = ('sphinxlatex',)
 
@@ -74,7 +74,7 @@ class LaTeXWriter(writers.Writer):  # type: ignore[misc]
         ('Document class', ['--docclass'], {'default': 'manual'}),
         ('Author', ['--author'], {'default': ''}),
     ))
-    settings_defaults: dict[str, Any] = {}
+    settings_defaults: ClassVar[dict[str, Any]] = {}
 
     theme: Theme
 
@@ -83,6 +83,7 @@ def __init__(self, builder: LaTeXBuilder) -> None:
         self.builder = builder
 
     def translate(self) -> None:
+        assert isinstance(self.document, nodes.document)
         visitor = self.builder.create_translator(self.document, self.builder, self.theme)
         self.document.walkabout(visitor)
         self.output = cast(LaTeXTranslator, visitor).astext()
diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py
index d9c1c89776d..2f0b6aff2f6 100644
--- a/sphinx/writers/texinfo.py
+++ b/sphinx/writers/texinfo.py
@@ -6,7 +6,7 @@
 import textwrap
 from collections.abc import Iterable, Iterator
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
 
@@ -104,12 +104,12 @@ def smart_capwords(s: str, sep: str | None = None) -> str:
     return (sep or ' ').join(words)
 
 
-class TexinfoWriter(writers.Writer):  # type: ignore[misc]
+class TexinfoWriter(writers.Writer):  # type: ignore[type-arg]
     """Texinfo writer for generating Texinfo documents."""
 
     supported = ('texinfo', 'texi')
 
-    settings_spec: tuple[str, Any, tuple[tuple[str, list[str], dict[str, str]], ...]] = (
+    settings_spec = (
         'Texinfo Specific Options', None, (
             ("Name of the Info file", ['--texinfo-filename'], {'default': ''}),
             ('Dir entry', ['--texinfo-dir-entry'], {'default': ''}),
@@ -117,7 +117,7 @@ class TexinfoWriter(writers.Writer):  # type: ignore[misc]
             ('Category', ['--texinfo-dir-category'], {'default':
                                                       'Miscellaneous'})))
 
-    settings_defaults: dict[str, Any] = {}
+    settings_defaults: ClassVar[dict[str, Any]] = {}
 
     output: str
 
@@ -128,6 +128,7 @@ def __init__(self, builder: TexinfoBuilder) -> None:
         self.builder = builder
 
     def translate(self) -> None:
+        assert isinstance(self.document, nodes.document)
         visitor = self.builder.create_translator(self.document, self.builder)
         self.visitor = cast(TexinfoTranslator, visitor)
         self.document.walkabout(visitor)
diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py
index 67eca45f1f7..c44a837e509 100644
--- a/sphinx/writers/text.py
+++ b/sphinx/writers/text.py
@@ -7,7 +7,7 @@
 import textwrap
 from collections.abc import Iterable, Iterator, Sequence
 from itertools import chain, groupby, pairwise
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 from docutils import nodes, writers
 from docutils.utils import column_width
@@ -356,10 +356,10 @@ def my_wrap(text: str, width: int = MAXWIDTH, **kwargs: Any) -> list[str]:
     return w.wrap(text)
 
 
-class TextWriter(writers.Writer):  # type: ignore[misc]
+class TextWriter(writers.Writer):  # type: ignore[type-arg]
     supported = ('text',)
     settings_spec = ('No options here.', '', ())
-    settings_defaults: dict[str, Any] = {}
+    settings_defaults: ClassVar[dict[str, Any]] = {}
 
     output: str
 
@@ -368,6 +368,7 @@ def __init__(self, builder: TextBuilder) -> None:
         self.builder = builder
 
     def translate(self) -> None:
+        assert isinstance(self.document, nodes.document)
         visitor = self.builder.create_translator(self.document, self.builder)
         self.document.walkabout(visitor)
         self.output = cast(TextTranslator, visitor).body
diff --git a/tests/test_markup/test_markup.py b/tests/test_markup/test_markup.py
index a8307e108d3..dc37051b89d 100644
--- a/tests/test_markup/test_markup.py
+++ b/tests/test_markup/test_markup.py
@@ -30,7 +30,8 @@ def settings(app):
         # DeprecationWarning: The frontend.OptionParser class will be replaced
         # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
         optparser = frontend.OptionParser(
-            components=(RstParser, HTMLWriter, LaTeXWriter), defaults=default_settings
+            components=(RstParser, HTMLWriter, LaTeXWriter),  # type: ignore[arg-type]
+            defaults=default_settings,
         )
     settings = optparser.get_default_values()
     settings.smart_quotes = True

From e1c5f6d31468c2b2cb66b2bae8dc40a60dc63178 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 16:00:53 +0100
Subject: [PATCH 23/29] Enable automatic formatting for ``sphinx/cmd/``
 (#12966)

---
 .ruff.toml               |   1 -
 sphinx/cmd/build.py      | 378 +++++++++++++++++++++---------
 sphinx/cmd/make_mode.py  | 117 +++++-----
 sphinx/cmd/quickstart.py | 486 +++++++++++++++++++++++++++------------
 4 files changed, 679 insertions(+), 303 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 629cee4280f..5f86b0a4740 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -445,7 +445,6 @@ exclude = [
     "sphinx/addnodes.py",
     "sphinx/application.py",
     "sphinx/builders/*",
-    "sphinx/cmd/*",
     "sphinx/config.py",
     "sphinx/domains/*",
     "sphinx/environment/*",
diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py
index 9f6cf2a3363..3c3d8e4b4de 100644
--- a/sphinx/cmd/build.py
+++ b/sphinx/cmd/build.py
@@ -32,19 +32,23 @@
     from typing import Protocol
 
     class SupportsWrite(Protocol):
-        def write(self, text: str, /) -> int | None:
-            ...
+        def write(self, text: str, /) -> int | None: ...  # NoQA: E704
 
 
 def handle_exception(
-    app: Sphinx | None, args: Any, exception: BaseException, stderr: TextIO = sys.stderr,
+    app: Sphinx | None,
+    args: Any,
+    exception: BaseException,
+    stderr: TextIO = sys.stderr,
 ) -> None:
     if isinstance(exception, bdb.BdbQuit):
         return
 
     if args.pdb:
-        print(red(__('Exception occurred while building, starting debugger:')),
-              file=stderr)
+        print(
+            red(__('Exception occurred while building, starting debugger:')),
+            file=stderr,
+        )
         traceback.print_exc()
         pdb.post_mortem(sys.exc_info()[2])
     else:
@@ -69,30 +73,60 @@ def handle_exception(
             print(red(__('Encoding error:')), file=stderr)
             print(terminal_safe(str(exception)), file=stderr)
             tbpath = save_traceback(app, exception)
-            print(red(__('The full traceback has been saved in %s, if you want '
-                         'to report the issue to the developers.') % tbpath),
-                  file=stderr)
-        elif isinstance(exception, RuntimeError) and 'recursion depth' in str(exception):
+            print(
+                red(
+                    __(
+                        'The full traceback has been saved in %s, if you want '
+                        'to report the issue to the developers.'
+                    )
+                    % tbpath
+                ),
+                file=stderr,
+            )
+        elif (
+            isinstance(exception, RuntimeError)
+            and 'recursion depth' in str(exception)
+        ):  # fmt: skip
             print(red(__('Recursion error:')), file=stderr)
             print(terminal_safe(str(exception)), file=stderr)
             print(file=stderr)
-            print(__('This can happen with very large or deeply nested source '
-                     'files. You can carefully increase the default Python '
-                     'recursion limit of 1000 in conf.py with e.g.:'), file=stderr)
+            print(
+                __(
+                    'This can happen with very large or deeply nested source '
+                    'files. You can carefully increase the default Python '
+                    'recursion limit of 1000 in conf.py with e.g.:'
+                ),
+                file=stderr,
+            )
             print('    import sys; sys.setrecursionlimit(1500)', file=stderr)
         else:
             print(red(__('Exception occurred:')), file=stderr)
             print(format_exception_cut_frames().rstrip(), file=stderr)
             tbpath = save_traceback(app, exception)
-            print(red(__('The full traceback has been saved in %s, if you '
-                         'want to report the issue to the developers.') % tbpath),
-                  file=stderr)
-            print(__('Please also report this if it was a user error, so '
-                     'that a better error message can be provided next time.'),
-                  file=stderr)
-            print(__('A bug report can be filed in the tracker at '
-                     '<https://github.com/sphinx-doc/sphinx/issues>. Thanks!'),
-                  file=stderr)
+            print(
+                red(
+                    __(
+                        'The full traceback has been saved in %s, if you '
+                        'want to report the issue to the developers.'
+                    )
+                    % tbpath
+                ),
+                file=stderr,
+            )
+            print(
+                __(
+                    'Please also report this if it was a user error, so '
+                    'that a better error message can be provided next time.'
+                ),
+                file=stderr,
+            )
+            print(
+                __(
+                    'A bug report can be filed in the tracker at '
+                    '<https://github.com/sphinx-doc/sphinx/issues>. Thanks!'
+                ),
+                file=stderr,
+            )
 
 
 def jobs_argument(value: str) -> int:
@@ -106,7 +140,9 @@ def jobs_argument(value: str) -> int:
     else:
         jobs = int(value)
         if jobs <= 0:
-            raise argparse.ArgumentTypeError(__('job number should be a positive number'))
+            raise argparse.ArgumentTypeError(
+                __('job number should be a positive number')
+            )
         else:
             return jobs
 
@@ -130,85 +166,203 @@ def get_parser() -> argparse.ArgumentParser:
 
 By default, everything that is outdated is built. Output only for selected
 files can be built by specifying individual filenames.
-"""))
-
-    parser.add_argument('--version', action='version', dest='show_version',
-                        version=f'%(prog)s {__display_version__}')
-
-    parser.add_argument('sourcedir', metavar='SOURCE_DIR',
-                        help=__('path to documentation source files'))
-    parser.add_argument('outputdir', metavar='OUTPUT_DIR',
-                        help=__('path to output directory'))
-    parser.add_argument('filenames', nargs='*',
-                        help=__('(optional) a list of specific files to rebuild. '
-                                'Ignored if --write-all is specified'))
+"""),
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        dest='show_version',
+        version=f'%(prog)s {__display_version__}',
+    )
+
+    parser.add_argument(
+        'sourcedir', metavar='SOURCE_DIR', help=__('path to documentation source files')
+    )
+    parser.add_argument(
+        'outputdir', metavar='OUTPUT_DIR', help=__('path to output directory')
+    )
+    parser.add_argument(
+        'filenames',
+        nargs='*',
+        help=__(
+            '(optional) a list of specific files to rebuild. '
+            'Ignored if --write-all is specified'
+        ),
+    )
 
     group = parser.add_argument_group(__('general options'))
-    group.add_argument('--builder', '-b', metavar='BUILDER', dest='builder',
-                       default='html',
-                       help=__("builder to use (default: 'html')"))
-    group.add_argument('--jobs', '-j', metavar='N', default=1, type=jobs_argument,
-                       dest='jobs',
-                       help=__('run in parallel with N processes, when possible. '
-                               "'auto' uses the number of CPU cores"))
-    group.add_argument('--write-all', '-a', action='store_true', dest='force_all',
-                       help=__('write all files (default: only write new and '
-                               'changed files)'))
-    group.add_argument('--fresh-env', '-E', action='store_true', dest='freshenv',
-                       help=__("don't use a saved environment, always read "
-                               'all files'))
+    group.add_argument(
+        '--builder',
+        '-b',
+        metavar='BUILDER',
+        dest='builder',
+        default='html',
+        help=__("builder to use (default: 'html')"),
+    )
+    group.add_argument(
+        '--jobs',
+        '-j',
+        metavar='N',
+        default=1,
+        type=jobs_argument,
+        dest='jobs',
+        help=__(
+            'run in parallel with N processes, when possible. '
+            "'auto' uses the number of CPU cores"
+        ),
+    )
+    group.add_argument(
+        '--write-all',
+        '-a',
+        action='store_true',
+        dest='force_all',
+        help=__('write all files (default: only write new and ' 'changed files)'),
+    )
+    group.add_argument(
+        '--fresh-env',
+        '-E',
+        action='store_true',
+        dest='freshenv',
+        help=__("don't use a saved environment, always read " 'all files'),
+    )
 
     group = parser.add_argument_group(__('path options'))
-    group.add_argument('--doctree-dir', '-d', metavar='PATH', dest='doctreedir',
-                       help=__('directory for doctree and environment files '
-                               '(default: OUTPUT_DIR/.doctrees)'))
-    group.add_argument('--conf-dir', '-c', metavar='PATH', dest='confdir',
-                       help=__('directory for the configuration file (conf.py) '
-                               '(default: SOURCE_DIR)'))
+    group.add_argument(
+        '--doctree-dir',
+        '-d',
+        metavar='PATH',
+        dest='doctreedir',
+        help=__(
+            'directory for doctree and environment files '
+            '(default: OUTPUT_DIR/.doctrees)'
+        ),
+    )
+    group.add_argument(
+        '--conf-dir',
+        '-c',
+        metavar='PATH',
+        dest='confdir',
+        help=__(
+            'directory for the configuration file (conf.py) ' '(default: SOURCE_DIR)'
+        ),
+    )
 
     group = parser.add_argument_group('build configuration options')
-    group.add_argument('--isolated', '-C', action='store_true', dest='noconfig',
-                       help=__('use no configuration file, only use settings from -D options'))
-    group.add_argument('--define', '-D', metavar='setting=value', action='append',
-                       dest='define', default=[],
-                       help=__('override a setting in configuration file'))
-    group.add_argument('--html-define', '-A', metavar='name=value', action='append',
-                       dest='htmldefine', default=[],
-                       help=__('pass a value into HTML templates'))
-    group.add_argument('--tag', '-t', metavar='TAG', action='append',
-                       dest='tags', default=[],
-                       help=__('define tag: include "only" blocks with TAG'))
-    group.add_argument('--nitpicky', '-n', action='store_true', dest='nitpicky',
-                       help=__('nitpicky mode: warn about all missing references'))
+    group.add_argument(
+        '--isolated',
+        '-C',
+        action='store_true',
+        dest='noconfig',
+        help=__('use no configuration file, only use settings from -D options'),
+    )
+    group.add_argument(
+        '--define',
+        '-D',
+        metavar='setting=value',
+        action='append',
+        dest='define',
+        default=[],
+        help=__('override a setting in configuration file'),
+    )
+    group.add_argument(
+        '--html-define',
+        '-A',
+        metavar='name=value',
+        action='append',
+        dest='htmldefine',
+        default=[],
+        help=__('pass a value into HTML templates'),
+    )
+    group.add_argument(
+        '--tag',
+        '-t',
+        metavar='TAG',
+        action='append',
+        dest='tags',
+        default=[],
+        help=__('define tag: include "only" blocks with TAG'),
+    )
+    group.add_argument(
+        '--nitpicky',
+        '-n',
+        action='store_true',
+        dest='nitpicky',
+        help=__('nitpicky mode: warn about all missing references'),
+    )
 
     group = parser.add_argument_group(__('console output options'))
-    group.add_argument('--verbose', '-v', action='count', dest='verbosity',
-                       default=0,
-                       help=__('increase verbosity (can be repeated)'))
-    group.add_argument('--quiet', '-q', action='store_true', dest='quiet',
-                       help=__('no output on stdout, just warnings on stderr'))
-    group.add_argument('--silent', '-Q', action='store_true', dest='really_quiet',
-                       help=__('no output at all, not even warnings'))
-    group.add_argument('--color', action='store_const', dest='color',
-                       const='yes', default='auto',
-                       help=__('do emit colored output (default: auto-detect)'))
-    group.add_argument('--no-color', '-N', action='store_const', dest='color',
-                       const='no',
-                       help=__('do not emit colored output (default: auto-detect)'))
+    group.add_argument(
+        '--verbose',
+        '-v',
+        action='count',
+        dest='verbosity',
+        default=0,
+        help=__('increase verbosity (can be repeated)'),
+    )
+    group.add_argument(
+        '--quiet',
+        '-q',
+        action='store_true',
+        dest='quiet',
+        help=__('no output on stdout, just warnings on stderr'),
+    )
+    group.add_argument(
+        '--silent',
+        '-Q',
+        action='store_true',
+        dest='really_quiet',
+        help=__('no output at all, not even warnings'),
+    )
+    group.add_argument(
+        '--color',
+        action='store_const',
+        dest='color',
+        const='yes',
+        default='auto',
+        help=__('do emit colored output (default: auto-detect)'),
+    )
+    group.add_argument(
+        '--no-color',
+        '-N',
+        action='store_const',
+        dest='color',
+        const='no',
+        help=__('do not emit colored output (default: auto-detect)'),
+    )
 
     group = parser.add_argument_group(__('warning control options'))
-    group.add_argument('--warning-file', '-w', metavar='FILE', dest='warnfile',
-                       help=__('write warnings (and errors) to given file'))
-    group.add_argument('--fail-on-warning', '-W', action='store_true', dest='warningiserror',
-                       help=__('turn warnings into errors'))
+    group.add_argument(
+        '--warning-file',
+        '-w',
+        metavar='FILE',
+        dest='warnfile',
+        help=__('write warnings (and errors) to given file'),
+    )
+    group.add_argument(
+        '--fail-on-warning',
+        '-W',
+        action='store_true',
+        dest='warningiserror',
+        help=__('turn warnings into errors'),
+    )
     group.add_argument('--keep-going', action='store_true', help=argparse.SUPPRESS)
-    group.add_argument('--show-traceback', '-T', action='store_true', dest='traceback',
-                       help=__('show full traceback on exception'))
-    group.add_argument('--pdb', '-P', action='store_true', dest='pdb',
-                       help=__('run Pdb on exception'))
-    group.add_argument('--exception-on-warning', action='store_true',
-                       dest='exception_on_warning',
-                       help=__('raise an exception on warnings'))
+    group.add_argument(
+        '--show-traceback',
+        '-T',
+        action='store_true',
+        dest='traceback',
+        help=__('show full traceback on exception'),
+    )
+    group.add_argument(
+        '--pdb', '-P', action='store_true', dest='pdb', help=__('run Pdb on exception')
+    )
+    group.add_argument(
+        '--exception-on-warning',
+        action='store_true',
+        dest='exception_on_warning',
+        help=__('raise an exception on warnings'),
+    )
 
     if parser.prog == '__main__.py':
         parser.prog = 'sphinx-build'
@@ -219,11 +373,13 @@ def get_parser() -> argparse.ArgumentParser:
 def make_main(argv: Sequence[str]) -> int:
     """Sphinx build "make mode" entry."""
     from sphinx.cmd import make_mode
+
     return make_mode.run_make_mode(argv[1:])
 
 
-def _parse_arguments(parser: argparse.ArgumentParser,
-                     argv: Sequence[str]) -> argparse.Namespace:
+def _parse_arguments(
+    parser: argparse.ArgumentParser, argv: Sequence[str]
+) -> argparse.Namespace:
     args = parser.parse_args(argv)
     return args
 
@@ -243,7 +399,9 @@ def _parse_doctreedir(doctreedir: str, outputdir: str) -> str:
 
 
 def _validate_filenames(
-    parser: argparse.ArgumentParser, force_all: bool, filenames: list[str],
+    parser: argparse.ArgumentParser,
+    force_all: bool,
+    filenames: list[str],
 ) -> None:
     if force_all and filenames:
         parser.error(__('cannot combine -a option and filenames'))
@@ -276,10 +434,9 @@ def _parse_logging(
             warnfile = path.abspath(warnfile)
             ensuredir(path.dirname(warnfile))
             # the caller is responsible for closing this file descriptor
-            warnfp = open(warnfile, 'w', encoding="utf-8")  # NoQA: SIM115
+            warnfp = open(warnfile, 'w', encoding='utf-8')  # NoQA: SIM115
         except Exception as exc:
-            parser.error(__('cannot open warning file %r: %s') % (
-                warnfile, exc))
+            parser.error(__('cannot open warning file %r: %s') % (warnfile, exc))
         warning = TeeStripANSI(warning, warnfp)  # type: ignore[assignment]
         error = warning
 
@@ -326,23 +483,33 @@ def build_main(argv: Sequence[str]) -> int:
     _validate_filenames(parser, args.force_all, args.filenames)
     _validate_colour_support(args.color)
     args.status, args.warning, args.error, warnfp = _parse_logging(
-        parser, args.quiet, args.really_quiet, args.warnfile)
+        parser, args.quiet, args.really_quiet, args.warnfile
+    )
     args.confoverrides = _parse_confoverrides(
-        parser, args.define, args.htmldefine, args.nitpicky)
+        parser, args.define, args.htmldefine, args.nitpicky
+    )
 
     app = None
     try:
         confdir = args.confdir or args.sourcedir
         with patch_docutils(confdir), docutils_namespace():
             app = Sphinx(
-                srcdir=args.sourcedir, confdir=args.confdir,
-                outdir=args.outputdir, doctreedir=args.doctreedir,
-                buildername=args.builder, confoverrides=args.confoverrides,
-                status=args.status, warning=args.warning,
-                freshenv=args.freshenv, warningiserror=args.warningiserror,
+                srcdir=args.sourcedir,
+                confdir=args.confdir,
+                outdir=args.outputdir,
+                doctreedir=args.doctreedir,
+                buildername=args.builder,
+                confoverrides=args.confoverrides,
+                status=args.status,
+                warning=args.warning,
+                freshenv=args.freshenv,
+                warningiserror=args.warningiserror,
                 tags=args.tags,
-                verbosity=args.verbosity, parallel=args.jobs, keep_going=False,
-                pdb=args.pdb, exception_on_warning=args.exception_on_warning,
+                verbosity=args.verbosity,
+                parallel=args.jobs,
+                keep_going=False,
+                pdb=args.pdb,
+                exception_on_warning=args.exception_on_warning,
             )
             app.build(args.force_all, args.filenames)
             return app.statuscode
@@ -390,6 +557,7 @@ def main(argv: Sequence[str] = (), /) -> int:
         return _bug_report_info()
     if argv[:1] == ['-M']:
         from sphinx.cmd import make_mode
+
         return make_mode.run_make_mode(argv[1:])
     else:
         return build_main(argv)
diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py
index d1ba3fccf9c..b590c423e85 100644
--- a/sphinx/cmd/make_mode.py
+++ b/sphinx/cmd/make_mode.py
@@ -29,31 +29,34 @@
     from collections.abc import Sequence
 
 BUILDERS = [
-    ("",      "html",        "to make standalone HTML files"),
-    ("",      "dirhtml",     "to make HTML files named index.html in directories"),
-    ("",      "singlehtml",  "to make a single large HTML file"),
-    ("",      "pickle",      "to make pickle files"),
-    ("",      "json",        "to make JSON files"),
-    ("",      "htmlhelp",    "to make HTML files and an HTML help project"),
-    ("",      "qthelp",      "to make HTML files and a qthelp project"),
-    ("",      "devhelp",     "to make HTML files and a Devhelp project"),
-    ("",      "epub",        "to make an epub"),
-    ("",      "latex",       "to make LaTeX files, you can set PAPER=a4 or PAPER=letter"),
-    ("posix", "latexpdf",    "to make LaTeX and PDF files (default pdflatex)"),
-    ("posix", "latexpdfja",  "to make LaTeX files and run them through platex/dvipdfmx"),
-    ("",      "text",        "to make text files"),
-    ("",      "man",         "to make manual pages"),
-    ("",      "texinfo",     "to make Texinfo files"),
-    ("posix", "info",        "to make Texinfo files and run them through makeinfo"),
-    ("",      "gettext",     "to make PO message catalogs"),
-    ("",      "changes",     "to make an overview of all changed/added/deprecated items"),
-    ("",      "xml",         "to make Docutils-native XML files"),
-    ("",      "pseudoxml",   "to make pseudoxml-XML files for display purposes"),
-    ("",      "linkcheck",   "to check all external links for integrity"),
-    ("",      "doctest",     "to run all doctests embedded in the documentation "
-                             "(if enabled)"),
-    ("",      "coverage",    "to run coverage check of the documentation (if enabled)"),
-    ("",      "clean",       "to remove everything in the build directory"),
+    ('', 'html', 'to make standalone HTML files'),
+    ('', 'dirhtml', 'to make HTML files named index.html in directories'),
+    ('', 'singlehtml', 'to make a single large HTML file'),
+    ('', 'pickle', 'to make pickle files'),
+    ('', 'json', 'to make JSON files'),
+    ('', 'htmlhelp', 'to make HTML files and an HTML help project'),
+    ('', 'qthelp', 'to make HTML files and a qthelp project'),
+    ('', 'devhelp', 'to make HTML files and a Devhelp project'),
+    ('', 'epub', 'to make an epub'),
+    ('', 'latex', 'to make LaTeX files, you can set PAPER=a4 or PAPER=letter'),
+    ('posix', 'latexpdf', 'to make LaTeX and PDF files (default pdflatex)'),
+    ('posix', 'latexpdfja', 'to make LaTeX files and run them through platex/dvipdfmx'),
+    ('', 'text', 'to make text files'),
+    ('', 'man', 'to make manual pages'),
+    ('', 'texinfo', 'to make Texinfo files'),
+    ('posix', 'info', 'to make Texinfo files and run them through makeinfo'),
+    ('', 'gettext', 'to make PO message catalogs'),
+    ('', 'changes', 'to make an overview of all changed/added/deprecated items'),
+    ('', 'xml', 'to make Docutils-native XML files'),
+    ('', 'pseudoxml', 'to make pseudoxml-XML files for display purposes'),
+    ('', 'linkcheck', 'to check all external links for integrity'),
+    (
+        '',
+        'doctest',
+        'to run all doctests embedded in the documentation ' '(if enabled)',
+    ),
+    ('', 'coverage', 'to run coverage check of the documentation (if enabled)'),
+    ('', 'clean', 'to remove everything in the build directory'),
 ]
 
 
@@ -72,15 +75,15 @@ def build_clean(self) -> int:
         if not path.exists(self.build_dir):
             return 0
         elif not path.isdir(self.build_dir):
-            print("Error: %r is not a directory!" % self.build_dir)
+            print('Error: %r is not a directory!' % self.build_dir)
             return 1
         elif source_dir == build_dir:
-            print("Error: %r is same as source directory!" % self.build_dir)
+            print('Error: %r is same as source directory!' % self.build_dir)
             return 1
         elif path.commonpath([source_dir, build_dir]) == build_dir:
-            print("Error: %r directory contains source directory!" % self.build_dir)
+            print('Error: %r directory contains source directory!' % self.build_dir)
             return 1
-        print("Removing everything under %r..." % self.build_dir)
+        print('Removing everything under %r...' % self.build_dir)
         for item in os.listdir(self.build_dir):
             rmtree(self.build_dir_join(item))
         return 0
@@ -89,7 +92,7 @@ def build_help(self) -> None:
         if not color_terminal():
             nocolor()
 
-        print(bold("Sphinx v%s" % sphinx.__display_version__))
+        print(bold('Sphinx v%s' % sphinx.__display_version__))
         print("Please use `make %s' where %s is one of" % ((blue('target'),) * 2))
         for osname, bname, description in BUILDERS:
             if not osname or os.name == osname:
@@ -108,29 +111,34 @@ def build_latexpdf(self) -> int:
             with chdir(self.build_dir_join('latex')):
                 if '-Q' in self.opts:
                     with open('__LATEXSTDOUT__', 'w') as outfile:
-                        returncode = subprocess.call([makecmd,
-                                                      'all-pdf',
-                                                      'LATEXOPTS=-halt-on-error',
-                                                      ],
-                                                     stdout=outfile,
-                                                     stderr=subprocess.STDOUT,
-                                                     )
+                        returncode = subprocess.call(
+                            [
+                                makecmd,
+                                'all-pdf',
+                                'LATEXOPTS=-halt-on-error',
+                            ],
+                            stdout=outfile,
+                            stderr=subprocess.STDOUT,
+                        )
                     if returncode:
-                        print('Latex error: check %s' %
-                              self.build_dir_join('latex', '__LATEXSTDOUT__')
-                              )
+                        print(
+                            'Latex error: check %s'
+                            % self.build_dir_join('latex', '__LATEXSTDOUT__')
+                        )
                 elif '-q' in self.opts:
                     returncode = subprocess.call(
-                        [makecmd,
-                         'all-pdf',
-                         'LATEXOPTS=-halt-on-error',
-                         'LATEXMKOPTS=-silent',
-                         ],
+                        [
+                            makecmd,
+                            'all-pdf',
+                            'LATEXOPTS=-halt-on-error',
+                            'LATEXMKOPTS=-silent',
+                        ],
                     )
                     if returncode:
-                        print('Latex error: check .log file in %s' %
-                              self.build_dir_join('latex')
-                              )
+                        print(
+                            'Latex error: check .log file in %s'
+                            % self.build_dir_join('latex')
+                        )
                 else:
                     returncode = subprocess.call([makecmd, 'all-pdf'])
                 return returncode
@@ -184,8 +192,10 @@ def run_generic_build(self, builder: str, doctreedir: str | None = None) -> int:
             doctreedir = self.build_dir_join('doctrees')
 
         args = [
-            '--builder', builder,
-            '--doctree-dir', doctreedir,
+            '--builder',
+            builder,
+            '--doctree-dir',
+            doctreedir,
             self.source_dir,
             self.build_dir_join(builder),
         ]
@@ -194,8 +204,11 @@ def run_generic_build(self, builder: str, doctreedir: str | None = None) -> int:
 
 def run_make_mode(args: Sequence[str]) -> int:
     if len(args) < 3:
-        print('Error: at least 3 arguments (builder, source '
-              'dir, build dir) are required.', file=sys.stderr)
+        print(
+            'Error: at least 3 arguments (builder, source '
+            'dir, build dir) are required.',
+            file=sys.stderr,
+        )
         return 1
 
     builder_name = args[0]
diff --git a/sphinx/cmd/quickstart.py b/sphinx/cmd/quickstart.py
index 4ae4556ca68..cbc9aafa673 100644
--- a/sphinx/cmd/quickstart.py
+++ b/sphinx/cmd/quickstart.py
@@ -13,14 +13,15 @@
 # try to import readline, unix specific enhancement
 try:
     import readline
-    if TYPE_CHECKING and sys.platform == "win32":  # always false, for type checking
+
+    if TYPE_CHECKING and sys.platform == 'win32':  # always false, for type checking
         raise ImportError
     READLINE_AVAILABLE = True
     if readline.__doc__ and 'libedit' in readline.__doc__:
-        readline.parse_and_bind("bind ^I rl_complete")
+        readline.parse_and_bind('bind ^I rl_complete')
         USE_LIBEDIT = True
     else:
-        readline.parse_and_bind("tab: complete")
+        readline.parse_and_bind('tab: complete')
         USE_LIBEDIT = False
 except ImportError:
     READLINE_AVAILABLE = False
@@ -90,7 +91,7 @@ class ValidationError(Exception):
 def is_path(x: str) -> str:
     x = path.expanduser(x)
     if not path.isdir(x):
-        raise ValidationError(__("Please enter a valid path name."))
+        raise ValidationError(__('Please enter a valid path name.'))
     return x
 
 
@@ -106,7 +107,7 @@ def allow_empty(x: str) -> str:
 
 def nonempty(x: str) -> str:
     if not x:
-        raise ValidationError(__("Please enter some text."))
+        raise ValidationError(__('Please enter some text.'))
     return x
 
 
@@ -115,6 +116,7 @@ def val(x: str) -> str:
         if x not in l:
             raise ValidationError(__('Please enter one of %s.') % ', '.join(l))
         return x
+
     return val
 
 
@@ -135,7 +137,9 @@ def ok(x: str) -> str:
 
 
 def do_prompt(
-    text: str, default: str | None = None, validator: Callable[[str], Any] = nonempty,
+    text: str,
+    default: str | None = None,
+    validator: Callable[[str], Any] = nonempty,
 ) -> str | bool:
     while True:
         if default is not None:
@@ -205,10 +209,16 @@ def ask_user(d: dict[str, Any]) -> None:
     * makefile:  make Makefile
     * batchfile: make command file
     """
-    print(bold(__('Welcome to the Sphinx %s quickstart utility.')) % __display_version__)
+    print(
+        bold(__('Welcome to the Sphinx %s quickstart utility.')) % __display_version__
+    )
     print()
-    print(__('Please enter values for the following settings (just press Enter to\n'
-             'accept a default value, if one is given in brackets).'))
+    print(
+        __(
+            'Please enter values for the following settings (just press Enter to\n'
+            'accept a default value, if one is given in brackets).'
+        )
+    )
 
     if 'path' in d:
         print()
@@ -218,90 +228,146 @@ def ask_user(d: dict[str, Any]) -> None:
         print(__('Enter the root path for documentation.'))
         d['path'] = do_prompt(__('Root path for the documentation'), '.', is_path)
 
-    while path.isfile(path.join(d['path'], 'conf.py')) or \
-            path.isfile(path.join(d['path'], 'source', 'conf.py')):
+    while path.isfile(path.join(d['path'], 'conf.py')) or path.isfile(
+        path.join(d['path'], 'source', 'conf.py')
+    ):
         print()
-        print(bold(__('Error: an existing conf.py has been found in the '
-                      'selected root path.')))
+        print(
+            bold(
+                __(
+                    'Error: an existing conf.py has been found in the '
+                    'selected root path.'
+                )
+            )
+        )
         print(__('sphinx-quickstart will not overwrite existing Sphinx projects.'))
         print()
-        d['path'] = do_prompt(__('Please enter a new root path (or just Enter to exit)'),
-                              '', is_path_or_empty)
+        d['path'] = do_prompt(
+            __('Please enter a new root path (or just Enter to exit)'),
+            '',
+            is_path_or_empty,
+        )
         if not d['path']:
             raise SystemExit(1)
 
     if 'sep' not in d:
         print()
-        print(__('You have two options for placing the build directory for Sphinx output.\n'
-                 'Either, you use a directory "_build" within the root path, or you separate\n'
-                 '"source" and "build" directories within the root path.'))
-        d['sep'] = do_prompt(__('Separate source and build directories (y/n)'), 'n', boolean)
+        print(
+            __(
+                'You have two options for placing the build directory for Sphinx output.\n'
+                'Either, you use a directory "_build" within the root path, or you separate\n'
+                '"source" and "build" directories within the root path.'
+            )
+        )
+        d['sep'] = do_prompt(
+            __('Separate source and build directories (y/n)'), 'n', boolean
+        )
 
     if 'dot' not in d:
         print()
-        print(__('Inside the root directory, two more directories will be created; "_templates"\n'      # NoQA: E501
-                 'for custom HTML templates and "_static" for custom stylesheets and other static\n'    # NoQA: E501
-                 'files. You can enter another prefix (such as ".") to replace the underscore.'))       # NoQA: E501
+        print(
+            __(
+                'Inside the root directory, two more directories will be created; "_templates"\n'  # NoQA: E501
+                'for custom HTML templates and "_static" for custom stylesheets and other static\n'  # NoQA: E501
+                'files. You can enter another prefix (such as ".") to replace the underscore.'
+            )
+        )  # NoQA: E501
         d['dot'] = do_prompt(__('Name prefix for templates and static dir'), '_', ok)
 
     if 'project' not in d:
         print()
-        print(__('The project name will occur in several places in the built documentation.'))
+        print(
+            __(
+                'The project name will occur in several places in the built documentation.'
+            )
+        )
         d['project'] = do_prompt(__('Project name'))
     if 'author' not in d:
         d['author'] = do_prompt(__('Author name(s)'))
 
     if 'version' not in d:
         print()
-        print(__('Sphinx has the notion of a "version" and a "release" for the\n'
-                 'software. Each version can have multiple releases. For example, for\n'
-                 'Python the version is something like 2.5 or 3.0, while the release is\n'
-                 "something like 2.5.1 or 3.0a1. If you don't need this dual structure,\n"
-                 'just set both to the same value.'))
+        print(
+            __(
+                'Sphinx has the notion of a "version" and a "release" for the\n'
+                'software. Each version can have multiple releases. For example, for\n'
+                'Python the version is something like 2.5 or 3.0, while the release is\n'
+                "something like 2.5.1 or 3.0a1. If you don't need this dual structure,\n"
+                'just set both to the same value.'
+            )
+        )
         d['version'] = do_prompt(__('Project version'), '', allow_empty)
     if 'release' not in d:
         d['release'] = do_prompt(__('Project release'), d['version'], allow_empty)
 
     if 'language' not in d:
         print()
-        print(__(
-            'If the documents are to be written in a language other than English,\n'
-            'you can select a language here by its language code. Sphinx will then\n'
-            'translate text that it generates into that language.\n'
-            '\n'
-            'For a list of supported codes, see\n'
-            'https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.',
-        ))
+        print(
+            __(
+                'If the documents are to be written in a language other than English,\n'
+                'you can select a language here by its language code. Sphinx will then\n'
+                'translate text that it generates into that language.\n'
+                '\n'
+                'For a list of supported codes, see\n'
+                'https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.',
+            )
+        )
         d['language'] = do_prompt(__('Project language'), 'en')
         if d['language'] == 'en':
             d['language'] = None
 
     if 'suffix' not in d:
         print()
-        print(__('The file name suffix for source files. Commonly, this is either ".txt"\n'
-                 'or ".rst". Only files with this suffix are considered documents.'))
+        print(
+            __(
+                'The file name suffix for source files. Commonly, this is either ".txt"\n'
+                'or ".rst". Only files with this suffix are considered documents.'
+            )
+        )
         d['suffix'] = do_prompt(__('Source file suffix'), '.rst', suffix)
 
     if 'master' not in d:
         print()
-        print(__('One document is special in that it is considered the top node of the\n'
-                 '"contents tree", that is, it is the root of the hierarchical structure\n'
-                 'of the documents. Normally, this is "index", but if your "index"\n'
-                 'document is a custom template, you can also set this to another filename.'))
-        d['master'] = do_prompt(__('Name of your master document (without suffix)'), 'index')
-
-    while path.isfile(path.join(d['path'], d['master'] + d['suffix'])) or \
-            path.isfile(path.join(d['path'], 'source', d['master'] + d['suffix'])):
+        print(
+            __(
+                'One document is special in that it is considered the top node of the\n'
+                '"contents tree", that is, it is the root of the hierarchical structure\n'
+                'of the documents. Normally, this is "index", but if your "index"\n'
+                'document is a custom template, you can also set this to another filename.'
+            )
+        )
+        d['master'] = do_prompt(
+            __('Name of your master document (without suffix)'), 'index'
+        )
+
+    while (
+        path.isfile(path.join(d['path'], d['master'] + d['suffix']))
+        or path.isfile(path.join(d['path'], 'source', d['master'] + d['suffix']))
+    ):  # fmt: skip
         print()
-        print(bold(__('Error: the master file %s has already been found in the '
-                      'selected root path.') % (d['master'] + d['suffix'])))
+        print(
+            bold(
+                __(
+                    'Error: the master file %s has already been found in the '
+                    'selected root path.'
+                )
+                % (d['master'] + d['suffix'])
+            )
+        )
         print(__('sphinx-quickstart will not overwrite the existing file.'))
         print()
-        d['master'] = do_prompt(__('Please enter a new file name, or rename the '
-                                   'existing file and press Enter'), d['master'])
+        d['master'] = do_prompt(
+            __(
+                'Please enter a new file name, or rename the '
+                'existing file and press Enter'
+            ),
+            d['master'],
+        )
 
     if 'extensions' not in d:
-        print(__('Indicate which of the following Sphinx extensions should be enabled:'))
+        print(
+            __('Indicate which of the following Sphinx extensions should be enabled:')
+        )
         d['extensions'] = []
         for name, description in EXTENSIONS.items():
             if do_prompt(f'{name}: {description} (y/n)', 'n', boolean):
@@ -309,19 +375,29 @@ def ask_user(d: dict[str, Any]) -> None:
 
         # Handle conflicting options
         if {'sphinx.ext.imgmath', 'sphinx.ext.mathjax'}.issubset(d['extensions']):
-            print(__('Note: imgmath and mathjax cannot be enabled at the same time. '
-                     'imgmath has been deselected.'))
+            print(
+                __(
+                    'Note: imgmath and mathjax cannot be enabled at the same time. '
+                    'imgmath has been deselected.'
+                )
+            )
             d['extensions'].remove('sphinx.ext.imgmath')
 
     if 'makefile' not in d:
         print()
-        print(__('A Makefile and a Windows command file can be generated for you so that you\n'
-                 "only have to run e.g. `make html' instead of invoking sphinx-build\n"
-                 'directly.'))
+        print(
+            __(
+                'A Makefile and a Windows command file can be generated for you so that you\n'
+                "only have to run e.g. `make html' instead of invoking sphinx-build\n"
+                'directly.'
+            )
+        )
         d['makefile'] = do_prompt(__('Create Makefile? (y/n)'), 'y', boolean)
 
     if 'batchfile' not in d:
-        d['batchfile'] = do_prompt(__('Create Windows command file? (y/n)'), 'y', boolean)
+        d['batchfile'] = do_prompt(
+            __('Create Windows command file? (y/n)'), 'y', boolean
+        )
     print()
 
 
@@ -345,7 +421,7 @@ def generate(
     d.setdefault('extensions', [])
     d['copyright'] = time.strftime('%Y') + ', ' + d['author']
 
-    d["path"] = os.path.abspath(d['path'])
+    d['path'] = os.path.abspath(d['path'])
     ensuredir(d['path'])
 
     srcdir = path.join(d['path'], 'source') if d['sep'] else d['path']
@@ -356,10 +432,14 @@ def generate(
         d['exclude_patterns'] = ''
     else:
         builddir = path.join(srcdir, d['dot'] + 'build')
-        exclude_patterns = map(repr, [
-            d['dot'] + 'build',
-            'Thumbs.db', '.DS_Store',
-        ])
+        exclude_patterns = map(
+            repr,
+            [
+                d['dot'] + 'build',
+                'Thumbs.db',
+                '.DS_Store',
+            ],
+        )
         d['exclude_patterns'] = ', '.join(exclude_patterns)
     ensuredir(builddir)
     ensuredir(path.join(srcdir, d['dot'] + 'templates'))
@@ -377,17 +457,16 @@ def write_file(fpath: str, content: str, newline: str | None = None) -> None:
 
     conf_path = os.path.join(templatedir, 'conf.py.jinja') if templatedir else None
     if not conf_path or not path.isfile(conf_path):
-        conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py.jinja')
-    with open(conf_path, encoding="utf-8") as f:
+        conf_path = os.path.join(
+            package_dir, 'templates', 'quickstart', 'conf.py.jinja'
+        )
+    with open(conf_path, encoding='utf-8') as f:
         conf_text = f.read()
 
     write_file(path.join(srcdir, 'conf.py'), template.render_string(conf_text, d))
 
     masterfile = path.join(srcdir, d['master'] + d['suffix'])
     if template._has_custom_template('quickstart/master_doc.rst.jinja'):
-        msg = ('A custom template `master_doc.rst.jinja` found. It has been renamed to '
-               '`root_doc.rst.jinja`.  Please rename it on your project too.')
-        print(colorize('red', msg))
         write_file(masterfile, template.render('quickstart/master_doc.rst.jinja', d))
     else:
         write_file(masterfile, template.render('quickstart/root_doc.rst.jinja', d))
@@ -399,30 +478,50 @@ def write_file(fpath: str, content: str, newline: str | None = None) -> None:
         d['rsrcdir'] = 'source' if d['sep'] else '.'
         d['rbuilddir'] = 'build' if d['sep'] else d['dot'] + 'build'
         # use binary mode, to avoid writing \r\n on Windows
-        write_file(path.join(d['path'], 'Makefile'),
-                   template.render(makefile_template, d), '\n')
+        write_file(
+            path.join(d['path'], 'Makefile'),
+            template.render(makefile_template, d),
+            '\n',
+        )
 
     if d['batchfile'] is True:
         d['rsrcdir'] = 'source' if d['sep'] else '.'
         d['rbuilddir'] = 'build' if d['sep'] else d['dot'] + 'build'
-        write_file(path.join(d['path'], 'make.bat'),
-                   template.render(batchfile_template, d), '\r\n')
+        write_file(
+            path.join(d['path'], 'make.bat'),
+            template.render(batchfile_template, d),
+            '\r\n',
+        )
 
     if silent:
         return
     print()
     print(bold(__('Finished: An initial directory structure has been created.')))
     print()
-    print(__('You should now populate your master file %s and create other documentation\n'
-             'source files. ') % masterfile, end='')
+    print(
+        __(
+            'You should now populate your master file %s and create other documentation\n'
+            'source files. '
+        )
+        % masterfile,
+        end='',
+    )
     if d['makefile'] or d['batchfile']:
-        print(__('Use the Makefile to build the docs, like so:\n'
-                 '   make builder'))
+        print(__('Use the Makefile to build the docs, like so:\n' '   make builder'))
     else:
-        print(__('Use the sphinx-build command to build the docs, like so:\n'
-                 '   sphinx-build -b builder %s %s') % (srcdir, builddir))
-    print(__('where "builder" is one of the supported builders, '
-             'e.g. html, latex or linkcheck.'))
+        print(
+            __(
+                'Use the sphinx-build command to build the docs, like so:\n'
+                '   sphinx-build -b builder %s %s'
+            )
+            % (srcdir, builddir)
+        )
+    print(
+        __(
+            'where "builder" is one of the supported builders, '
+            'e.g. html, latex or linkcheck.'
+        )
+    )
     print()
 
 
@@ -454,83 +553,166 @@ def valid_dir(d: dict[str, Any]) -> bool:
 
 def get_parser() -> argparse.ArgumentParser:
     description = __(
-        "\n"
-        "Generate required files for a Sphinx project.\n"
-        "\n"
-        "sphinx-quickstart is an interactive tool that asks some questions about your\n"
-        "project and then generates a complete documentation directory and sample\n"
-        "Makefile to be used with sphinx-build.\n",
+        '\n'
+        'Generate required files for a Sphinx project.\n'
+        '\n'
+        'sphinx-quickstart is an interactive tool that asks some questions about your\n'
+        'project and then generates a complete documentation directory and sample\n'
+        'Makefile to be used with sphinx-build.\n',
     )
     parser = argparse.ArgumentParser(
         usage='%(prog)s [OPTIONS] <PROJECT_DIR>',
-        epilog=__("For more information, visit <https://www.sphinx-doc.org/>."),
-        description=description)
+        epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
+        description=description,
+    )
 
-    parser.add_argument('-q', '--quiet', action='store_true', dest='quiet',
-                        default=None,
-                        help=__('quiet mode'))
-    parser.add_argument('--version', action='version', dest='show_version',
-                        version='%%(prog)s %s' % __display_version__)
+    parser.add_argument(
+        '-q',
+        '--quiet',
+        action='store_true',
+        dest='quiet',
+        default=None,
+        help=__('quiet mode'),
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        dest='show_version',
+        version='%%(prog)s %s' % __display_version__,
+    )
 
-    parser.add_argument('path', metavar='PROJECT_DIR', default='.', nargs='?',
-                        help=__('project root'))
+    parser.add_argument(
+        'path', metavar='PROJECT_DIR', default='.', nargs='?', help=__('project root')
+    )
 
     group = parser.add_argument_group(__('Structure options'))
-    group.add_argument('--sep', action='store_true', dest='sep', default=None,
-                       help=__('if specified, separate source and build dirs'))
-    group.add_argument('--no-sep', action='store_false', dest='sep',
-                       help=__('if specified, create build dir under source dir'))
-    group.add_argument('--dot', metavar='DOT', default='_',
-                       help=__('replacement for dot in _templates etc.'))
+    group.add_argument(
+        '--sep',
+        action='store_true',
+        dest='sep',
+        default=None,
+        help=__('if specified, separate source and build dirs'),
+    )
+    group.add_argument(
+        '--no-sep',
+        action='store_false',
+        dest='sep',
+        help=__('if specified, create build dir under source dir'),
+    )
+    group.add_argument(
+        '--dot',
+        metavar='DOT',
+        default='_',
+        help=__('replacement for dot in _templates etc.'),
+    )
 
     group = parser.add_argument_group(__('Project basic options'))
-    group.add_argument('-p', '--project', metavar='PROJECT', dest='project',
-                       help=__('project name'))
-    group.add_argument('-a', '--author', metavar='AUTHOR', dest='author',
-                       help=__('author names'))
-    group.add_argument('-v', metavar='VERSION', dest='version', default='',
-                       help=__('version of project'))
-    group.add_argument('-r', '--release', metavar='RELEASE', dest='release',
-                       help=__('release of project'))
-    group.add_argument('-l', '--language', metavar='LANGUAGE', dest='language',
-                       help=__('document language'))
-    group.add_argument('--suffix', metavar='SUFFIX', default='.rst',
-                       help=__('source file suffix'))
-    group.add_argument('--master', metavar='MASTER', default='index',
-                       help=__('master document name'))
-    group.add_argument('--epub', action='store_true', default=False,
-                       help=__('use epub'))
+    group.add_argument(
+        '-p', '--project', metavar='PROJECT', dest='project', help=__('project name')
+    )
+    group.add_argument(
+        '-a', '--author', metavar='AUTHOR', dest='author', help=__('author names')
+    )
+    group.add_argument(
+        '-v',
+        metavar='VERSION',
+        dest='version',
+        default='',
+        help=__('version of project'),
+    )
+    group.add_argument(
+        '-r',
+        '--release',
+        metavar='RELEASE',
+        dest='release',
+        help=__('release of project'),
+    )
+    group.add_argument(
+        '-l',
+        '--language',
+        metavar='LANGUAGE',
+        dest='language',
+        help=__('document language'),
+    )
+    group.add_argument(
+        '--suffix', metavar='SUFFIX', default='.rst', help=__('source file suffix')
+    )
+    group.add_argument(
+        '--master', metavar='MASTER', default='index', help=__('master document name')
+    )
+    group.add_argument(
+        '--epub', action='store_true', default=False, help=__('use epub')
+    )
 
     group = parser.add_argument_group(__('Extension options'))
     for ext in EXTENSIONS:
-        group.add_argument('--ext-%s' % ext, action='append_const',
-                           const='sphinx.ext.%s' % ext, dest='extensions',
-                           help=__('enable %s extension') % ext)
-    group.add_argument('--extensions', metavar='EXTENSIONS', dest='extensions',
-                       action='append', help=__('enable arbitrary extensions'))
+        group.add_argument(
+            '--ext-%s' % ext,
+            action='append_const',
+            const='sphinx.ext.%s' % ext,
+            dest='extensions',
+            help=__('enable %s extension') % ext,
+        )
+    group.add_argument(
+        '--extensions',
+        metavar='EXTENSIONS',
+        dest='extensions',
+        action='append',
+        help=__('enable arbitrary extensions'),
+    )
 
     group = parser.add_argument_group(__('Makefile and Batchfile creation'))
-    group.add_argument('--makefile', action='store_true', dest='makefile', default=True,
-                       help=__('create makefile'))
-    group.add_argument('--no-makefile', action='store_false', dest='makefile',
-                       help=__('do not create makefile'))
-    group.add_argument('--batchfile', action='store_true', dest='batchfile', default=True,
-                       help=__('create batchfile'))
-    group.add_argument('--no-batchfile', action='store_false',
-                       dest='batchfile',
-                       help=__('do not create batchfile'))
+    group.add_argument(
+        '--makefile',
+        action='store_true',
+        dest='makefile',
+        default=True,
+        help=__('create makefile'),
+    )
+    group.add_argument(
+        '--no-makefile',
+        action='store_false',
+        dest='makefile',
+        help=__('do not create makefile'),
+    )
+    group.add_argument(
+        '--batchfile',
+        action='store_true',
+        dest='batchfile',
+        default=True,
+        help=__('create batchfile'),
+    )
+    group.add_argument(
+        '--no-batchfile',
+        action='store_false',
+        dest='batchfile',
+        help=__('do not create batchfile'),
+    )
     # --use-make-mode is a no-op from Sphinx 8.
-    group.add_argument('-m', '--use-make-mode', action='store_true',
-                       dest='make_mode', default=True,
-                       help=__('use make-mode for Makefile/make.bat'))
+    group.add_argument(
+        '-m',
+        '--use-make-mode',
+        action='store_true',
+        dest='make_mode',
+        default=True,
+        help=__('use make-mode for Makefile/make.bat'),
+    )
 
     group = parser.add_argument_group(__('Project templating'))
-    group.add_argument('-t', '--templatedir', metavar='TEMPLATEDIR',
-                       dest='templatedir',
-                       help=__('template directory for template files'))
-    group.add_argument('-d', metavar='NAME=VALUE', action='append',
-                       dest='variables',
-                       help=__('define a template variable'))
+    group.add_argument(
+        '-t',
+        '--templatedir',
+        metavar='TEMPLATEDIR',
+        dest='templatedir',
+        help=__('template directory for template files'),
+    )
+    group.add_argument(
+        '-d',
+        metavar='NAME=VALUE',
+        action='append',
+        dest='variables',
+        help=__('define a template variable'),
+    )
 
     return parser
 
@@ -563,8 +745,12 @@ def main(argv: Sequence[str] = (), /) -> int:
     try:
         if 'quiet' in d:
             if not {'project', 'author'}.issubset(d):
-                print(__('"quiet" is specified, but any of "project" or '
-                         '"author" is not specified.'))
+                print(
+                    __(
+                        '"quiet" is specified, but any of "project" or '
+                        '"author" is not specified.'
+                    )
+                )
                 return 1
 
         if {'quiet', 'project', 'author'}.issubset(d):
@@ -577,10 +763,20 @@ def main(argv: Sequence[str] = (), /) -> int:
 
             if not valid_dir(d):
                 print()
-                print(bold(__('Error: specified path is not a directory, or sphinx'
-                              ' files already exist.')))
-                print(__('sphinx-quickstart only generate into a empty directory.'
-                         ' Please specify a new root path.'))
+                print(
+                    bold(
+                        __(
+                            'Error: specified path is not a directory, or sphinx'
+                            ' files already exist.'
+                        )
+                    )
+                )
+                print(
+                    __(
+                        'sphinx-quickstart only generate into a empty directory.'
+                        ' Please specify a new root path.'
+                    )
+                )
                 return 1
         else:
             ask_user(d)

From 81c6f1e8cc28edce99864aadb1fcaa7eb7e4ce33 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 16:28:02 +0100
Subject: [PATCH 24/29] Enable automatic formatting for ``sphinx/search/``
 (#12967)

---
 .ruff.toml                |   5 +-
 sphinx/search/__init__.py | 160 +++++++++++++++++++++++++-------------
 sphinx/search/da.py       |   6 +-
 sphinx/search/de.py       |   6 +-
 sphinx/search/en.py       |   8 +-
 sphinx/search/es.py       |   6 +-
 sphinx/search/fi.py       |   6 +-
 sphinx/search/fr.py       |   6 +-
 sphinx/search/hu.py       |   6 +-
 sphinx/search/it.py       |   6 +-
 sphinx/search/ja.py       |  67 ++++++++++------
 sphinx/search/nl.py       |   6 +-
 sphinx/search/no.py       |   6 +-
 sphinx/search/pt.py       |   6 +-
 sphinx/search/ro.py       |   2 -
 sphinx/search/ru.py       |   6 +-
 sphinx/search/sv.py       |   6 +-
 sphinx/search/tr.py       |   2 -
 sphinx/search/zh.py       |  16 ++--
 19 files changed, 187 insertions(+), 145 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 5f86b0a4740..0d36f6d0c42 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -7,7 +7,7 @@ extend-exclude = [
     "tests/js/roots/*",
     "build/*",
     "doc/_build/*",
-    "sphinx/search/*",
+#    "sphinx/search/*",
     "doc/usage/extensions/example*.py",
 ]
 
@@ -411,6 +411,8 @@ select = [
 "sphinx/ext/autodoc/importer.py" = ["D402"]
 "sphinx/util/requests.py" = ["D402"]
 
+"sphinx/search/*" = ["E501"]
+
 "tests/*" = [
     "E501",
     "ANN",  # tests don't need annotations
@@ -475,7 +477,6 @@ exclude = [
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
     "sphinx/registry.py",
-    "sphinx/search/*",
     "sphinx/testing/*",
     "sphinx/transforms/*",
     "sphinx/writers/*",
diff --git a/sphinx/search/__init__.py b/sphinx/search/__init__.py
index e56a00d7b8a..e02e91a2e19 100644
--- a/sphinx/search/__init__.py
+++ b/sphinx/search/__init__.py
@@ -1,4 +1,5 @@
 """Create a full-text search index for offline search."""
+
 from __future__ import annotations
 
 import dataclasses
@@ -15,12 +16,13 @@
 from docutils.nodes import Element, Node
 
 from sphinx import addnodes, package_dir
-from sphinx.environment import BuildEnvironment
 from sphinx.util.index_entries import split_index_msg
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
+    from sphinx.environment import BuildEnvironment
+
 
 class SearchLanguage:
     """
@@ -52,10 +54,11 @@ class SearchLanguage:
        This class is used to preprocess search word which Sphinx HTML readers
        type, before searching index. Default implementation does nothing.
     """
+
     lang: str = ''
     language_name: str = ''
     stopwords: set[str] = set()
-    js_splitter_code: str = ""
+    js_splitter_code: str = ''
     js_stemmer_rawcode: str = ''
     js_stemmer_code = """
 /**
@@ -105,16 +108,14 @@ def word_filter(self, word: str) -> bool:
         Return true if the target word should be registered in the search index.
         This method is called after stemming.
         """
-        return (
-            len(word) == 0 or not (
-                ((len(word) < 3) and (12353 < ord(word[0]) < 12436)) or
-                (ord(word[0]) < 256 and (
-                    word in self.stopwords
-                ))))
+        return len(word) == 0 or not (
+            ((len(word) < 3) and (12353 < ord(word[0]) < 12436))
+            or (ord(word[0]) < 256 and (word in self.stopwords))
+        )
 
 
 # SearchEnglish imported after SearchLanguage is defined due to circular import
-from sphinx.search.en import SearchEnglish
+from sphinx.search.en import SearchEnglish  # NoQA: E402
 
 
 def parse_stop_word(source: str) -> set[str]:
@@ -165,10 +166,10 @@ def dumps(self, data: Any) -> str:
         return self.PREFIX + json.dumps(data, sort_keys=True) + self.SUFFIX
 
     def loads(self, s: str) -> Any:
-        data = s[len(self.PREFIX):-len(self.SUFFIX)]
-        if not data or not s.startswith(self.PREFIX) or not \
-           s.endswith(self.SUFFIX):
-            raise ValueError('invalid data')
+        data = s[len(self.PREFIX) : -len(self.SUFFIX)]
+        if not data or not s.startswith(self.PREFIX) or not s.endswith(self.SUFFIX):
+            msg = 'invalid data'
+            raise ValueError(msg)
         return json.loads(data)
 
     def dump(self, data: Any, f: IO[str]) -> None:
@@ -187,9 +188,8 @@ def _is_meta_keywords(
 ) -> bool:
     if node.get('name') == 'keywords':
         meta_lang = node.get('lang')
-        if meta_lang is None:  # lang not specified
-            return True
-        elif meta_lang == lang:  # matched to html_search_language
+        if meta_lang is None or meta_lang == lang:
+            # lang not specified or matched to html_search_language
             return True
 
     return False
@@ -222,8 +222,18 @@ def dispatch_visit(self, node: Node) -> None:
                 # Some people might put content in raw HTML that should be searched,
                 # so we just amateurishly strip HTML tags and index the remaining
                 # content
-                nodetext = re.sub(r'<style.*?</style>', '', node.astext(), flags=re.IGNORECASE|re.DOTALL)
-                nodetext = re.sub(r'<script.*?</script>', '', nodetext, flags=re.IGNORECASE|re.DOTALL)
+                nodetext = re.sub(
+                    r'<style.*?</style>',
+                    '',
+                    node.astext(),
+                    flags=re.IGNORECASE | re.DOTALL,
+                )
+                nodetext = re.sub(
+                    r'<script.*?</script>',
+                    '',
+                    nodetext,
+                    flags=re.IGNORECASE | re.DOTALL,
+                )
                 nodetext = re.sub(r'<[^<]+?>', '', nodetext)
                 self.found_words.extend(self.lang.split(nodetext))
             raise nodes.SkipNode
@@ -245,12 +255,15 @@ class IndexBuilder:
     Helper class that creates a search index based on the doctrees
     passed to the `feed` method.
     """
+
     formats = {
-        'json':     json,
-        'pickle':   pickle
+        'json': json,
+        'pickle': pickle,
     }
 
-    def __init__(self, env: BuildEnvironment, lang: str, options: dict[str, str], scoring: str) -> None:
+    def __init__(
+        self, env: BuildEnvironment, lang: str, options: dict[str, str], scoring: str
+    ) -> None:
         self.env = env
         # docname -> title
         self._titles: dict[str, str | None] = env._search_index_titles
@@ -261,9 +274,13 @@ def __init__(self, env: BuildEnvironment, lang: str, options: dict[str, str], sc
         # stemmed words in titles -> set(docname)
         self._title_mapping: dict[str, set[str]] = env._search_index_title_mapping
         # docname -> all titles in document
-        self._all_titles: dict[str, list[tuple[str, str | None]]] = env._search_index_all_titles
+        self._all_titles: dict[str, list[tuple[str, str | None]]] = (
+            env._search_index_all_titles
+        )
         # docname -> list(index entry)
-        self._index_entries: dict[str, list[tuple[str, str, str]]] = env._search_index_index_entries
+        self._index_entries: dict[str, list[tuple[str, str, str]]] = (
+            env._search_index_index_entries
+        )
         # objtype -> index
         self._objtypes: dict[tuple[str, str], int] = env._search_index_objtypes
         # objtype index -> (domain, type, objname (localized))
@@ -290,7 +307,7 @@ def __init__(self, env: BuildEnvironment, lang: str, options: dict[str, str], sc
                 self.js_scorer_code = fp.read().decode()
         else:
             self.js_scorer_code = ''
-        self.js_splitter_code = ""
+        self.js_splitter_code = ''
 
     def load(self, stream: IO, format: Any) -> None:
         """Reconstruct from frozen data."""
@@ -298,15 +315,15 @@ def load(self, stream: IO, format: Any) -> None:
             format = self.formats[format]
         frozen = format.load(stream)
         # if an old index is present, we treat it as not existing.
-        if not isinstance(frozen, dict) or \
-           frozen.get('envversion') != self.env.version:
-            raise ValueError('old format')
+        if not isinstance(frozen, dict) or frozen.get('envversion') != self.env.version:
+            msg = 'old format'
+            raise ValueError(msg)
         index2fn = frozen['docnames']
-        self._filenames = dict(zip(index2fn, frozen['filenames']))
-        self._titles = dict(zip(index2fn, frozen['titles']))
+        self._filenames = dict(zip(index2fn, frozen['filenames'], strict=True))
+        self._titles = dict(zip(index2fn, frozen['titles'], strict=True))
         self._all_titles = {}
 
-        for docname in self._titles.keys():
+        for docname in self._titles:
             self._all_titles[docname] = []
         for title, doc_tuples in frozen['alltitles'].items():
             for doc, titleid in doc_tuples:
@@ -331,8 +348,9 @@ def dump(self, stream: IO, format: Any) -> None:
             format = self.formats[format]
         format.dump(self.freeze(), stream)
 
-    def get_objects(self, fn2index: dict[str, int]
-                    ) -> dict[str, list[tuple[int, int, int, str, str]]]:
+    def get_objects(
+        self, fn2index: dict[str, int]
+    ) -> dict[str, list[tuple[int, int, int, str, str]]]:
         rv: dict[str, list[tuple[int, int, int, str, str]]] = {}
         otypes = self._objtypes
         onames = self._objnames
@@ -355,8 +373,11 @@ def get_objects(self, fn2index: dict[str, int]
                     otype = domain.object_types.get(type)
                     if otype:
                         # use str() to fire translation proxies
-                        onames[typeindex] = (domain.name, type,
-                                             str(domain.get_type_name(otype)))
+                        onames[typeindex] = (
+                            domain.name,
+                            type,
+                            str(domain.get_type_name(otype)),
+                        )
                     else:
                         onames[typeindex] = (domain.name, type, type)
                 if anchor == fullname:
@@ -368,7 +389,9 @@ def get_objects(self, fn2index: dict[str, int]
                 plist.append((fn2index[docname], typeindex, prio, shortanchor, name))
         return rv
 
-    def get_terms(self, fn2index: dict[str, int]) -> tuple[dict[str, list[int] | int], dict[str, list[int] | int]]:
+    def get_terms(
+        self, fn2index: dict[str, int]
+    ) -> tuple[dict[str, list[int] | int], dict[str, list[int] | int]]:
         """
         Return a mapping of document and title terms to their corresponding sorted document IDs.
 
@@ -377,10 +400,10 @@ def get_terms(self, fn2index: dict[str, int]) -> tuple[dict[str, list[int] | int
         of integers.
         """
         rvs: tuple[dict[str, list[int] | int], dict[str, list[int] | int]] = ({}, {})
-        for rv, mapping in zip(rvs, (self._mapping, self._title_mapping)):
+        for rv, mapping in zip(rvs, (self._mapping, self._title_mapping), strict=True):
             for k, v in mapping.items():
                 if len(v) == 1:
-                    fn, = v
+                    (fn,) = v
                     if fn in fn2index:
                         rv[k] = fn2index[fn]
                 else:
@@ -389,7 +412,7 @@ def get_terms(self, fn2index: dict[str, int]) -> tuple[dict[str, list[int] | int
 
     def freeze(self) -> dict[str, Any]:
         """Create a usable data structure for serializing."""
-        docnames, titles = zip(*sorted(self._titles.items()))
+        docnames, titles = zip(*sorted(self._titles.items()), strict=True)
         filenames = [self._filenames.get(docname) for docname in docnames]
         fn2index = {f: i for (i, f) in enumerate(docnames)}
         terms, title_terms = self.get_terms(fn2index)
@@ -406,15 +429,28 @@ def freeze(self) -> dict[str, Any]:
         index_entries: dict[str, list[tuple[int, str, bool]]] = {}
         for docname, entries in self._index_entries.items():
             for entry, entry_id, main_entry in entries:
-                index_entries.setdefault(entry.lower(), []).append((fn2index[docname], entry_id, main_entry == "main"))
+                index_entries.setdefault(entry.lower(), []).append((
+                    fn2index[docname],
+                    entry_id,
+                    main_entry == 'main',
+                ))
 
-        return dict(docnames=docnames, filenames=filenames, titles=titles, terms=terms,
-                    objects=objects, objtypes=objtypes, objnames=objnames,
-                    titleterms=title_terms, envversion=self.env.version,
-                    alltitles=alltitles, indexentries=index_entries)
+        return {
+            'docnames': docnames,
+            'filenames': filenames,
+            'titles': titles,
+            'terms': terms,
+            'objects': objects,
+            'objtypes': objtypes,
+            'objnames': objnames,
+            'titleterms': title_terms,
+            'envversion': self.env.version,
+            'alltitles': alltitles,
+            'indexentries': index_entries,
+        }
 
     def label(self) -> str:
-        return f"{self.lang.language_name} (code: {self.lang.lang})"
+        return f'{self.lang.language_name} (code: {self.lang.lang})'
 
     def prune(self, docnames: Iterable[str]) -> None:
         """Remove data for all docnames not in the list."""
@@ -434,7 +470,9 @@ def prune(self, docnames: Iterable[str]) -> None:
         for wordnames in self._title_mapping.values():
             wordnames.intersection_update(docnames)
 
-    def feed(self, docname: str, filename: str, title: str, doctree: nodes.document) -> None:
+    def feed(
+        self, docname: str, filename: str, title: str, doctree: nodes.document
+    ) -> None:
         """Feed a doctree to the index."""
         self._titles[docname] = title
         self._filenames[docname] = filename
@@ -495,15 +533,22 @@ def _visit_nodes(node: nodes.Node) -> None:
                     # Some people might put content in raw HTML that should be searched,
                     # so we just amateurishly strip HTML tags and index the remaining
                     # content
-                    nodetext = re.sub(r'<style.*?</style>', '', node.astext(),
-                                      flags=re.IGNORECASE | re.DOTALL)
-                    nodetext = re.sub(r'<script.*?</script>', '', nodetext,
-                                      flags=re.IGNORECASE | re.DOTALL)
+                    nodetext = re.sub(
+                        r'<style.*?</style>',
+                        '',
+                        node.astext(),
+                        flags=re.IGNORECASE | re.DOTALL,
+                    )
+                    nodetext = re.sub(
+                        r'<script.*?</script>',
+                        '',
+                        nodetext,
+                        flags=re.IGNORECASE | re.DOTALL,
+                    )
                     nodetext = re.sub(r'<[^<]+?>', '', nodetext)
                     word_store.words.extend(split(nodetext))
                 return
-            elif (isinstance(node, nodes.meta)
-                  and _is_meta_keywords(node, language)):
+            elif isinstance(node, nodes.meta) and _is_meta_keywords(node, language):
                 keywords = [keyword.strip() for keyword in node['content'].split(',')]
                 word_store.words.extend(keywords)
             elif isinstance(node, nodes.Text):
@@ -553,11 +598,16 @@ def get_js_stemmer_code(self) -> str:
         """Returns JS code that will be inserted into language_data.js."""
         if self.lang.js_stemmer_rawcode:
             js_dir = path.join(package_dir, 'search', 'minified-js')
-            with open(path.join(js_dir, 'base-stemmer.js'), encoding='utf-8') as js_file:
+            with open(
+                path.join(js_dir, 'base-stemmer.js'), encoding='utf-8'
+            ) as js_file:
                 base_js = js_file.read()
-            with open(path.join(js_dir, self.lang.js_stemmer_rawcode), encoding='utf-8') as js_file:
+            with open(
+                path.join(js_dir, self.lang.js_stemmer_rawcode), encoding='utf-8'
+            ) as js_file:
                 language_js = js_file.read()
-            return ('%s\n%s\nStemmer = %sStemmer;' %
-                    (base_js, language_js, self.lang.language_name))
+            return (
+                f'{base_js}\n{language_js}\nStemmer = {self.lang.language_name}Stemmer;'
+            )
         else:
             return self.lang.js_stemmer_code
diff --git a/sphinx/search/da.py b/sphinx/search/da.py
index 47c57448533..a56114bb6ba 100644
--- a/sphinx/search/da.py
+++ b/sphinx/search/da.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-danish_stopwords = parse_stop_word('''
+danish_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/danish/stop.txt
 og           | and
 i            | in
@@ -104,7 +102,7 @@
 thi          | for (conj)
 jer          | you
 sådan        | such, like this/like that
-''')
+""")
 
 
 class SearchDanish(SearchLanguage):
diff --git a/sphinx/search/de.py b/sphinx/search/de.py
index dae52c9f8ef..37aa9ec8890 100644
--- a/sphinx/search/de.py
+++ b/sphinx/search/de.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-german_stopwords = parse_stop_word('''
+german_stopwords = parse_stop_word("""
 |source: https://snowball.tartarus.org/algorithms/german/stop.txt
 aber           |  but
 
@@ -287,7 +285,7 @@
 zur            |  zu + der
 zwar           |  indeed
 zwischen       |  between
-''')
+""")
 
 
 class SearchGerman(SearchLanguage):
diff --git a/sphinx/search/en.py b/sphinx/search/en.py
index a1f06bd3f2a..11ebb683836 100644
--- a/sphinx/search/en.py
+++ b/sphinx/search/en.py
@@ -2,13 +2,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage
 
-english_stopwords = set("""
+english_stopwords = set(
+    """
 a  and  are  as  at
 be  but  by
 for
@@ -18,7 +17,8 @@
 such
 that  the  their  then  there  these  they  this  to
 was  will  with
-""".split())
+""".split()
+)
 
 js_porter_stemmer = """
 /**
diff --git a/sphinx/search/es.py b/sphinx/search/es.py
index 247095b452b..5739c88172a 100644
--- a/sphinx/search/es.py
+++ b/sphinx/search/es.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-spanish_stopwords = parse_stop_word('''
+spanish_stopwords = parse_stop_word("""
 |source: https://snowball.tartarus.org/algorithms/spanish/stop.txt
 de             |  from, of
 la             |  the, her
@@ -347,7 +345,7 @@
 tenidos
 tenidas
 tened
-''')
+""")
 
 
 class SearchSpanish(SearchLanguage):
diff --git a/sphinx/search/fi.py b/sphinx/search/fi.py
index 5eca6e38472..f6c22264352 100644
--- a/sphinx/search/fi.py
+++ b/sphinx/search/fi.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-finnish_stopwords = parse_stop_word('''
+finnish_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/finnish/stop.txt
 | forms of BE
 
@@ -97,7 +95,7 @@
 niin   | so
 nyt    | now
 itse   | self
-''')
+""")
 
 
 class SearchFinnish(SearchLanguage):
diff --git a/sphinx/search/fr.py b/sphinx/search/fr.py
index 4d41cf4423c..7662737d6e3 100644
--- a/sphinx/search/fr.py
+++ b/sphinx/search/fr.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-french_stopwords = parse_stop_word('''
+french_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/french/stop.txt
 au             |  a + le
 aux            |  a + les
@@ -183,7 +181,7 @@
 quelles        |  which
 sans           |  without
 soi            |  oneself
-''')
+""")
 
 
 class SearchFrench(SearchLanguage):
diff --git a/sphinx/search/hu.py b/sphinx/search/hu.py
index ccd6ebec354..5c35b16fc65 100644
--- a/sphinx/search/hu.py
+++ b/sphinx/search/hu.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-hungarian_stopwords = parse_stop_word('''
+hungarian_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/hungarian/stop.txt
 | prepared by Anna Tordai
 a
@@ -210,7 +208,7 @@
 vele
 viszont
 volna
-''')
+""")
 
 
 class SearchHungarian(SearchLanguage):
diff --git a/sphinx/search/it.py b/sphinx/search/it.py
index 8436dfa5be7..60a5cf57720 100644
--- a/sphinx/search/it.py
+++ b/sphinx/search/it.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-italian_stopwords = parse_stop_word('''
+italian_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/italian/stop.txt
 ad             |  a (to) before vowel
 al             |  a + il
@@ -300,7 +298,7 @@
 stesse
 stessimo
 stessero
-''')
+""")
 
 
 class SearchItalian(SearchLanguage):
diff --git a/sphinx/search/ja.py b/sphinx/search/ja.py
index 7ff663292df..65e626fdd57 100644
--- a/sphinx/search/ja.py
+++ b/sphinx/search/ja.py
@@ -17,12 +17,14 @@
 
 try:
     import MeCab  # type: ignore[import-not-found]
+
     native_module = True
 except ImportError:
     native_module = False
 
 try:
     import janome.tokenizer  # type: ignore[import-not-found]
+
     janome_module = True
 except ImportError:
     janome_module = False
@@ -61,7 +63,8 @@ def split(self, input: str) -> list[str]:
             result = self.native.parse(input)
         else:
             result = self.ctypes_libmecab.mecab_sparse_tostr(
-                self.ctypes_mecab, input.encode(self.dict_encode))
+                self.ctypes_mecab, input.encode(self.dict_encode)
+            )
         return result.split(' ')
 
     def init_native(self, options: dict[str, str]) -> None:
@@ -89,7 +92,8 @@ def init_ctypes(self, options: dict[str, str]) -> None:
             if os.path.exists(lib):
                 libpath = lib
         if libpath is None:
-            raise RuntimeError('MeCab dynamic library is not available')
+            msg = 'MeCab dynamic library is not available'
+            raise RuntimeError(msg)
 
         param = 'mecab -Owakati'
         dict = options.get('dict')
@@ -101,11 +105,15 @@ def init_ctypes(self, options: dict[str, str]) -> None:
         self.ctypes_libmecab = ctypes.CDLL(libpath)
         self.ctypes_libmecab.mecab_new2.argtypes = (ctypes.c_char_p,)
         self.ctypes_libmecab.mecab_new2.restype = ctypes.c_void_p
-        self.ctypes_libmecab.mecab_sparse_tostr.argtypes = (ctypes.c_void_p, ctypes.c_char_p)
+        self.ctypes_libmecab.mecab_sparse_tostr.argtypes = (
+            ctypes.c_void_p,
+            ctypes.c_char_p,
+        )
         self.ctypes_libmecab.mecab_sparse_tostr.restype = ctypes.c_char_p
         self.ctypes_mecab = self.ctypes_libmecab.mecab_new2(param.encode(fs_enc))
         if self.ctypes_mecab is None:
-            raise SphinxError('mecab initialization failed')
+            msg = 'mecab initialization failed'
+            raise SphinxError(msg)
 
     def __del__(self) -> None:
         if self.ctypes_libmecab:
@@ -121,8 +129,11 @@ def __init__(self, options: dict[str, str]) -> None:
 
     def init_tokenizer(self) -> None:
         if not janome_module:
-            raise RuntimeError('Janome is not available')
-        self.tokenizer = janome.tokenizer.Tokenizer(udic=self.user_dict, udic_enc=self.user_dict_enc)
+            msg = 'Janome is not available'
+            raise RuntimeError(msg)
+        self.tokenizer = janome.tokenizer.Tokenizer(
+            udic=self.user_dict, udic_enc=self.user_dict_enc
+        )
 
     def split(self, input: str) -> list[str]:
         result = ' '.join(token.surface for token in self.tokenizer.tokenize(input))
@@ -130,14 +141,18 @@ def split(self, input: str) -> list[str]:
 
 
 class DefaultSplitter(BaseSplitter):
-    patterns_ = {re.compile(pattern): value for pattern, value in {
-        '[一二三四五六七八九十百千万億兆]': 'M',
-        '[一-龠々〆ヵヶ]': 'H',
-        '[ぁ-ん]': 'I',
-        '[ァ-ヴーｱ-ﾝﾞｰ]': 'K',
-        '[a-zA-Zａ-ｚＡ-Ｚ]': 'A',
-        '[0-9０-９]': 'N',
-    }.items()}
+    patterns_ = {
+        re.compile(pattern): value
+        for pattern, value in {
+            '[一二三四五六七八九十百千万億兆]': 'M',
+            '[一-龠々〆ヵヶ]': 'H',
+            '[ぁ-ん]': 'I',
+            '[ァ-ヴーｱ-ﾝﾞｰ]': 'K',
+            '[a-zA-Zａ-ｚＡ-Ｚ]': 'A',
+            '[0-9０-９]': 'N',
+        }.items()
+    }
+    # fmt: off
     BIAS__ = -332
     BC1__ = {'HH': 6, 'II': 2461, 'KH': 406, 'OH': -1378}
     BC2__ = {'AA': -3267, 'AI': 2744, 'AN': -878, 'HH': -4070, 'HM': -1711,
@@ -398,6 +413,7 @@ class DefaultSplitter(BaseSplitter):
              '委': 798, '学': -960, '市': 887, '広': -695, '後': 535, '業': -697,
              '相': 753, '社': -507, '福': 974, '空': -822, '者': 1811, '連': 463,
              '郎': 1082, '１': -270, 'Ｅ１': 306, 'ﾙ': -673, 'ﾝ': -496}
+    # fmt: on
 
     # ctype_
     def ctype_(self, char: str) -> str:
@@ -427,18 +443,18 @@ def split(self, input: str) -> list[str]:
 
         for i in range(4, len(seg) - 3):
             score = self.BIAS__
-            w1 = seg[i-3]
-            w2 = seg[i-2]
-            w3 = seg[i-1]
+            w1 = seg[i - 3]
+            w2 = seg[i - 2]
+            w3 = seg[i - 1]
             w4 = seg[i]
-            w5 = seg[i+1]
-            w6 = seg[i+2]
-            c1 = ctype[i-3]
-            c2 = ctype[i-2]
-            c3 = ctype[i-1]
+            w5 = seg[i + 1]
+            w6 = seg[i + 2]
+            c1 = ctype[i - 3]
+            c2 = ctype[i - 2]
+            c3 = ctype[i - 1]
             c4 = ctype[i]
-            c5 = ctype[i+1]
-            c6 = ctype[i+2]
+            c5 = ctype[i + 1]
+            c6 = ctype[i + 2]
             score += self.ts_(self.UP1__, p1)
             score += self.ts_(self.UP2__, p2)
             score += self.ts_(self.UP3__, p3)
@@ -470,7 +486,7 @@ def split(self, input: str) -> list[str]:
             score += self.ts_(self.TC2__, c2 + c3 + c4)
             score += self.ts_(self.TC3__, c3 + c4 + c5)
             score += self.ts_(self.TC4__, c4 + c5 + c6)
-#           score += self.ts_(self.TC5__, c4 + c5 + c6)
+            # score += self.ts_(self.TC5__, c4 + c5 + c6)
             score += self.ts_(self.UQ1__, p1 + c1)
             score += self.ts_(self.UQ2__, p2 + c2)
             score += self.ts_(self.UQ1__, p3 + c3)
@@ -501,6 +517,7 @@ class SearchJapanese(SearchLanguage):
     Japanese search implementation: uses no stemmer, but word splitting is quite
     complicated.
     """
+
     lang = 'ja'
     language_name = 'Japanese'
 
diff --git a/sphinx/search/nl.py b/sphinx/search/nl.py
index cb5e8c4f9a5..98f924dde86 100644
--- a/sphinx/search/nl.py
+++ b/sphinx/search/nl.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-dutch_stopwords = parse_stop_word('''
+dutch_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/dutch/stop.txt
 de             |  the
 en             |  and
@@ -111,7 +109,7 @@
 iemand         |  somebody
 geweest        |  been; past participle of 'be'
 andere         |  other
-''')
+""")
 
 
 class SearchDutch(SearchLanguage):
diff --git a/sphinx/search/no.py b/sphinx/search/no.py
index aa7c1043baa..dfc7786d46a 100644
--- a/sphinx/search/no.py
+++ b/sphinx/search/no.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-norwegian_stopwords = parse_stop_word('''
+norwegian_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/norwegian/stop.txt
 og             | and
 i              | in
@@ -186,7 +184,7 @@
 vort           | become *
 varte          | became *
 vart           | became *
-''')
+""")
 
 
 class SearchNorwegian(SearchLanguage):
diff --git a/sphinx/search/pt.py b/sphinx/search/pt.py
index 0cf96109aa7..bf9b7a3a2f8 100644
--- a/sphinx/search/pt.py
+++ b/sphinx/search/pt.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-portuguese_stopwords = parse_stop_word('''
+portuguese_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/portuguese/stop.txt
 de             |  of, from
 a              |  the; to, at; her
@@ -245,7 +243,7 @@
 teria
 teríamos
 teriam
-''')
+""")
 
 
 class SearchPortuguese(SearchLanguage):
diff --git a/sphinx/search/ro.py b/sphinx/search/ro.py
index f15b7a6bb12..0c00486319a 100644
--- a/sphinx/search/ro.py
+++ b/sphinx/search/ro.py
@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict, Set
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage
diff --git a/sphinx/search/ru.py b/sphinx/search/ru.py
index d6b817ebe15..e93046cba94 100644
--- a/sphinx/search/ru.py
+++ b/sphinx/search/ru.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-russian_stopwords = parse_stop_word('''
+russian_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/russian/stop.txt
 и              | and
 в              | in/into
@@ -235,7 +233,7 @@
   | можн
   | нужн
   | нельзя
-''')
+""")
 
 
 class SearchRussian(SearchLanguage):
diff --git a/sphinx/search/sv.py b/sphinx/search/sv.py
index b90e2276441..b4fa1bd06a2 100644
--- a/sphinx/search/sv.py
+++ b/sphinx/search/sv.py
@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage, parse_stop_word
 
-swedish_stopwords = parse_stop_word('''
+swedish_stopwords = parse_stop_word("""
 | source: https://snowball.tartarus.org/algorithms/swedish/stop.txt
 och            | and
 det            | it, this/that
@@ -124,7 +122,7 @@
 ert            | your
 era            | your
 vilkas         | whose
-''')
+""")
 
 
 class SearchSwedish(SearchLanguage):
diff --git a/sphinx/search/tr.py b/sphinx/search/tr.py
index fdfc18a227e..b999e1d96d8 100644
--- a/sphinx/search/tr.py
+++ b/sphinx/search/tr.py
@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Dict, Set
-
 import snowballstemmer
 
 from sphinx.search import SearchLanguage
diff --git a/sphinx/search/zh.py b/sphinx/search/zh.py
index e40c9a9fe9b..9446a7f9b31 100644
--- a/sphinx/search/zh.py
+++ b/sphinx/search/zh.py
@@ -11,11 +11,13 @@
 
 try:
     import jieba  # type: ignore[import-not-found]
+
     JIEBA = True
 except ImportError:
     JIEBA = False
 
-english_stopwords = set("""
+english_stopwords = set(
+    """
 a  and  are  as  at
 be  but  by
 for
@@ -25,7 +27,8 @@
 such
 that  the  their  then  there  these  they  this  to
 was  will  with
-""".split())
+""".split()
+)
 
 js_porter_stemmer = """
 /**
@@ -239,8 +242,7 @@ def split(self, input: str) -> list[str]:
         if JIEBA:
             chinese = list(jieba.cut_for_search(input))
 
-        latin1 = \
-            [term.strip() for term in self.latin1_letters.findall(input)]
+        latin1 = [term.strip() for term in self.latin1_letters.findall(input)]
         self.latin_terms.extend(latin1)
         return chinese + latin1
 
@@ -252,9 +254,9 @@ def stem(self, word: str) -> str:
         # if not stemmed, but would be too short after being stemmed
         # avoids some issues with acronyms
         should_not_be_stemmed = (
-            word in self.latin_terms and
-            len(word) >= 3 and
-            len(self.stemmer.stemWord(word.lower())) < 3
+            word in self.latin_terms
+            and len(word) >= 3
+            and len(self.stemmer.stemWord(word.lower())) < 3
         )
         if should_not_be_stemmed:
             return word.lower()

From 4dfddc533c7fdfcbaa399ff4af869812b58727bb Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 16:40:48 +0100
Subject: [PATCH 25/29] Enable automatic formatting for ``sphinx/environment/``
 (#12968)

---
 .ruff.toml                                    |   1 -
 sphinx/environment/__init__.py                | 119 ++++++++++-----
 sphinx/environment/adapters/indexentries.py   | 105 +++++++++----
 sphinx/environment/adapters/toctree.py        | 143 ++++++++++++------
 sphinx/environment/collectors/__init__.py     |  27 +++-
 sphinx/environment/collectors/asset.py        |  62 ++++++--
 sphinx/environment/collectors/dependencies.py |  12 +-
 sphinx/environment/collectors/metadata.py     |   9 +-
 sphinx/environment/collectors/title.py        |   9 +-
 sphinx/environment/collectors/toctree.py      |  70 ++++++---
 10 files changed, 392 insertions(+), 165 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 0d36f6d0c42..b142fcbd60f 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -449,7 +449,6 @@ exclude = [
     "sphinx/builders/*",
     "sphinx/config.py",
     "sphinx/domains/*",
-    "sphinx/environment/*",
     "sphinx/ext/autodoc/__init__.py",
     "sphinx/ext/autodoc/directive.py",
     "sphinx/ext/autodoc/importer.py",
diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py
index 31e5508d09e..056769e1ce1 100644
--- a/sphinx/environment/__init__.py
+++ b/sphinx/environment/__init__.py
@@ -274,7 +274,9 @@ def setup(self, app: Sphinx) -> None:
         self._update_settings(app.config)
 
     @staticmethod
-    def _config_status(*, old_config: Config | None, new_config: Config) -> tuple[int, str]:
+    def _config_status(
+        *, old_config: Config | None, new_config: Config
+    ) -> tuple[int, str]:
         """Report the differences between two Config objects.
 
         Returns a triple of:
@@ -306,7 +308,9 @@ def _config_status(*, old_config: Config | None, new_config: Config) -> tuple[in
     def _update_settings(self, config: Config) -> None:
         """Update settings by new config."""
         self.settings['input_encoding'] = config.source_encoding
-        self.settings['trim_footnote_reference_space'] = config.trim_footnote_reference_space
+        self.settings['trim_footnote_reference_space'] = (
+            config.trim_footnote_reference_space
+        )
         self.settings['language_code'] = config.language
 
         # Allow to disable by 3rd party extension (workaround)
@@ -331,9 +335,12 @@ def set_versioning_method(
             condition = versioning_conditions[method]
 
         if self.versioning_condition not in {None, condition}:
-            raise SphinxError(__('This environment is incompatible with the '
-                                 'selected builder, please choose another '
-                                 'doctree directory.'))
+            msg = __(
+                'This environment is incompatible with the '
+                'selected builder, please choose another '
+                'doctree directory.'
+            )
+            raise SphinxError(msg)
         self.versioning_condition = condition
         self.versioning_compare = compare
 
@@ -346,8 +353,9 @@ def clear_doc(self, docname: str) -> None:
 
         self.domains._clear_doc(docname)
 
-    def merge_info_from(self, docnames: Iterable[str], other: BuildEnvironment,
-                        app: Sphinx) -> None:
+    def merge_info_from(
+        self, docnames: Iterable[str], other: BuildEnvironment, app: Sphinx
+    ) -> None:
         """Merge global information gathered about *docnames* while reading them
         from the *other* environment.
 
@@ -390,12 +398,13 @@ def relfn2path(self, filename: str, docname: str | None = None) -> tuple[str, st
         if filename.startswith(('/', os.sep)):
             rel_fn = filename[1:]
         else:
-            docdir = path.dirname(self.doc2path(docname or self.docname,
-                                                base=False))
+            docdir = path.dirname(self.doc2path(docname or self.docname, base=False))
             rel_fn = path.join(docdir, filename)
 
-        return (canon_path(path.normpath(rel_fn)),
-                path.normpath(path.join(self.srcdir, rel_fn)))
+        return (
+            canon_path(path.normpath(rel_fn)),
+            path.normpath(path.join(self.srcdir, rel_fn)),
+        )
 
     @property
     def found_docs(self) -> set[str]:
@@ -407,9 +416,11 @@ def find_files(self, config: Config, builder: Builder) -> None:
         self.found_docs.
         """
         try:
-            exclude_paths = (self.config.exclude_patterns +
-                             self.config.templates_path +
-                             builder.get_asset_paths())
+            exclude_paths = (
+                self.config.exclude_patterns
+                + self.config.templates_path
+                + builder.get_asset_paths()
+            )
             self.project.discover(exclude_paths, self.config.include_patterns)
 
             # Current implementation is applying translated messages in the reading
@@ -420,18 +431,25 @@ def find_files(self, config: Config, builder: Builder) -> None:
             # move i18n process into the writing phase, and remove these lines.
             if builder.use_message_catalog:
                 # add catalog mo file dependency
-                repo = CatalogRepository(self.srcdir, self.config.locale_dirs,
-                                         self.config.language, self.config.source_encoding)
+                repo = CatalogRepository(
+                    self.srcdir,
+                    self.config.locale_dirs,
+                    self.config.language,
+                    self.config.source_encoding,
+                )
                 mo_paths = {c.domain: c.mo_path for c in repo.catalogs}
                 for docname in self.found_docs:
                     domain = docname_to_domain(docname, self.config.gettext_compact)
                     if domain in mo_paths:
                         self.dependencies[docname].add(mo_paths[domain])
         except OSError as exc:
-            raise DocumentError(__('Failed to scan documents in %s: %r') %
-                                (self.srcdir, exc)) from exc
+            raise DocumentError(
+                __('Failed to scan documents in %s: %r') % (self.srcdir, exc)
+            ) from exc
 
-    def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str], set[str]]:
+    def get_outdated_files(
+        self, config_changed: bool
+    ) -> tuple[set[str], set[str], set[str]]:
         """Return (added, changed, removed) sets."""
         # clear all files no longer present
         removed = set(self.all_docs) - self.found_docs
@@ -463,10 +481,12 @@ def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str],
                 mtime = self.all_docs[docname]
                 newmtime = _last_modified_time(self.doc2path(docname))
                 if newmtime > mtime:
-                    logger.debug('[build target] outdated %r: %s -> %s',
-                                 docname,
-                                 _format_rfc3339_microseconds(mtime),
-                                 _format_rfc3339_microseconds(newmtime))
+                    logger.debug(
+                        '[build target] outdated %r: %s -> %s',
+                        docname,
+                        _format_rfc3339_microseconds(mtime),
+                        _format_rfc3339_microseconds(newmtime),
+                    )
                     changed.add(docname)
                     continue
                 # finally, check the mtime of dependencies
@@ -477,7 +497,8 @@ def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str],
                         if not path.isfile(deppath):
                             logger.debug(
                                 '[build target] changed %r missing dependency %r',
-                                docname, deppath,
+                                docname,
+                                deppath,
                             )
                             changed.add(docname)
                             break
@@ -485,7 +506,8 @@ def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str],
                         if depmtime > mtime:
                             logger.debug(
                                 '[build target] outdated %r from dependency %r: %s -> %s',
-                                docname, deppath,
+                                docname,
+                                deppath,
                                 _format_rfc3339_microseconds(mtime),
                                 _format_rfc3339_microseconds(depmtime),
                             )
@@ -619,7 +641,10 @@ def get_and_resolve_doctree(
         # now, resolve all toctree nodes
         for toctreenode in doctree.findall(addnodes.toctree):
             result = toctree_adapters._resolve_toctree(
-                self, docname, builder, toctreenode,
+                self,
+                docname,
+                builder,
+                toctreenode,
                 prune=prune_toctrees,
                 includehidden=includehidden,
             )
@@ -630,9 +655,17 @@ def get_and_resolve_doctree(
 
         return doctree
 
-    def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toctree,
-                        prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-                        collapse: bool = False, includehidden: bool = False) -> Node | None:
+    def resolve_toctree(
+        self,
+        docname: str,
+        builder: Builder,
+        toctree: addnodes.toctree,
+        prune: bool = True,
+        maxdepth: int = 0,
+        titles_only: bool = False,
+        collapse: bool = False,
+        includehidden: bool = False,
+    ) -> Node | None:
         """Resolve a *toctree* node into individual bullet lists with titles
         as items, returning None (if no containing titles are found) or
         a new node.
@@ -645,7 +678,10 @@ def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toct
         be collapsed.
         """
         return toctree_adapters._resolve_toctree(
-            self, docname, builder, toctree,
+            self,
+            docname,
+            builder,
+            toctree,
             prune=prune,
             maxdepth=maxdepth,
             titles_only=titles_only,
@@ -653,8 +689,9 @@ def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toct
             includehidden=includehidden,
         )
 
-    def resolve_references(self, doctree: nodes.document, fromdocname: str,
-                           builder: Builder) -> None:
+    def resolve_references(
+        self, doctree: nodes.document, fromdocname: str, builder: Builder
+    ) -> None:
         self.apply_post_transforms(doctree, fromdocname)
 
     def apply_post_transforms(self, doctree: nodes.document, docname: str) -> None:
@@ -679,7 +716,7 @@ def collect_relations(self) -> dict[str, list[str | None]]:
 
         relations = {}
         docnames = _traverse_toctree(
-            traversed, None, self.config.root_doc, self.toctree_includes,
+            traversed, None, self.config.root_doc, self.toctree_includes
         )
         prev_doc = None
         parent, docname = next(docnames)
@@ -706,8 +743,9 @@ def check_consistency(self) -> None:
                     continue
                 if 'orphan' in self.metadata[docname]:
                     continue
-                logger.warning(__("document isn't included in any toctree"),
-                               location=docname)
+                logger.warning(
+                    __("document isn't included in any toctree"), location=docname
+                )
 
         # call check-consistency for all extensions
         self.domains._check_consistency()
@@ -721,9 +759,12 @@ def _traverse_toctree(
     toctree_includes: dict[str, list[str]],
 ) -> Iterator[tuple[str | None, str]]:
     if parent == docname:
-        logger.warning(__('self referenced toctree found. Ignored.'),
-                       location=docname, type='toc',
-                       subtype='circular')
+        logger.warning(
+            __('self referenced toctree found. Ignored.'),
+            location=docname,
+            type='toc',
+            subtype='circular',
+        )
         return
 
     # traverse toctree by pre-order
@@ -732,7 +773,7 @@ def _traverse_toctree(
 
     for child in toctree_includes.get(docname, ()):
         for sub_parent, sub_docname in _traverse_toctree(
-            traversed, docname, child, toctree_includes,
+            traversed, docname, child, toctree_includes
         ):
             if sub_docname not in traversed:
                 yield sub_parent, sub_docname
diff --git a/sphinx/environment/adapters/indexentries.py b/sphinx/environment/adapters/indexentries.py
index fbceeb56b0c..42ae170b233 100644
--- a/sphinx/environment/adapters/indexentries.py
+++ b/sphinx/environment/adapters/indexentries.py
@@ -40,10 +40,10 @@
                     tuple[
                         _IndexEntryTargets,
                         list[tuple[str, _IndexEntryTargets]],
-                        _IndexEntryCategoryKey
-                    ]
+                        _IndexEntryCategoryKey,
+                    ],
                 ]
-            ]
+            ],
         ]
     ]
 
@@ -80,41 +80,77 @@ def create_index(
                         try:
                             entry, sub_entry = _split_into(2, 'single', value)
                         except ValueError:
-                            entry, = _split_into(1, 'single', value)
+                            (entry,) = _split_into(1, 'single', value)
                             sub_entry = ''
-                        _add_entry(entry, sub_entry, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            entry, sub_entry, main, dic=new, link=uri, key=category_key
+                        )
                     elif entry_type == 'pair':
                         first, second = _split_into(2, 'pair', value)
-                        _add_entry(first, second, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(second, first, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            first, second, main, dic=new, link=uri, key=category_key
+                        )
+                        _add_entry(
+                            second, first, main, dic=new, link=uri, key=category_key
+                        )
                     elif entry_type == 'triple':
                         first, second, third = _split_into(3, 'triple', value)
-                        _add_entry(first, second + ' ' + third, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(second, third + ', ' + first, main,
-                                   dic=new, link=uri, key=category_key)
-                        _add_entry(third, first + ' ' + second, main,
-                                   dic=new, link=uri, key=category_key)
+                        _add_entry(
+                            first,
+                            second + ' ' + third,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
+                        _add_entry(
+                            second,
+                            third + ', ' + first,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
+                        _add_entry(
+                            third,
+                            first + ' ' + second,
+                            main,
+                            dic=new,
+                            link=uri,
+                            key=category_key,
+                        )
                     elif entry_type == 'see':
                         first, second = _split_into(2, 'see', value)
-                        _add_entry(first, _('see %s') % second, None,
-                                   dic=new, link=False, key=category_key)
+                        _add_entry(
+                            first,
+                            _('see %s') % second,
+                            None,
+                            dic=new,
+                            link=False,
+                            key=category_key,
+                        )
                     elif entry_type == 'seealso':
                         first, second = _split_into(2, 'see', value)
-                        _add_entry(first, _('see also %s') % second, None,
-                                   dic=new, link=False, key=category_key)
+                        _add_entry(
+                            first,
+                            _('see also %s') % second,
+                            None,
+                            dic=new,
+                            link=False,
+                            key=category_key,
+                        )
                     else:
-                        logger.warning(__('unknown index entry type %r'), entry_type,
-                                       location=docname)
+                        logger.warning(
+                            __('unknown index entry type %r'),
+                            entry_type,
+                            location=docname,
+                        )
                 except ValueError as err:
                     logger.warning(str(err), location=docname)
 
-        for (targets, sub_items, _category_key) in new.values():
+        for targets, sub_items, _category_key in new.values():
             targets.sort(key=_key_func_0)
-            for (sub_targets, _sub_category_key) in sub_items.values():
+            for sub_targets, _sub_category_key in sub_items.values():
                 sub_targets.sort(key=_key_func_0)
 
         new_list: list[tuple[str, _IndexEntry]] = sorted(new.items(), key=_key_func_1)
@@ -139,8 +175,8 @@ def create_index(
                         if old_key == m.group(1):
                             # prefixes match: add entry as subitem of the
                             # previous entry
-                            old_sub_items.setdefault(
-                                m.group(2), ([], category_key))[0].extend(targets)
+                            prev = old_sub_items.setdefault(m[2], ([], category_key))
+                            prev[0].extend(targets)
                             del new_list[i]
                             continue
                         old_key = m.group(1)
@@ -150,14 +186,13 @@ def create_index(
                 i += 1
 
         grouped = []
-        for (group_key, group) in groupby(new_list, _group_by_func):
+        for group_key, group in groupby(new_list, _group_by_func):
             group_list = []
             for group_entry in group:
                 entry_key, (targets, sub_items, category_key) = group_entry
                 pairs = [
                     (sub_key, sub_targets)
-                    for (sub_key, (sub_targets, _sub_category_key))
-                    in sub_items.items()
+                    for (sub_key, (sub_targets, _sub_category_key)) in sub_items.items()
                 ]
                 pairs.sort(key=_key_func_2)
                 group_list.append((entry_key, (targets, pairs, category_key)))
@@ -165,9 +200,15 @@ def create_index(
         return grouped
 
 
-def _add_entry(word: str, subword: str, main: str | None, *,
-               dic: _IndexEntryMap,
-               link: str | Literal[False], key: _IndexEntryCategoryKey) -> None:
+def _add_entry(
+    word: str,
+    subword: str,
+    main: str | None,
+    *,
+    dic: _IndexEntryMap,
+    link: str | Literal[False],
+    key: _IndexEntryCategoryKey,
+) -> None:
     entry = dic.setdefault(word, ([], {}, key))
     if subword:
         targets = entry[1].setdefault(subword, ([], key))[0]
diff --git a/sphinx/environment/adapters/toctree.py b/sphinx/environment/adapters/toctree.py
index 217cb0d41ef..edd873b5f44 100644
--- a/sphinx/environment/adapters/toctree.py
+++ b/sphinx/environment/adapters/toctree.py
@@ -24,7 +24,9 @@
 logger = logging.getLogger(__name__)
 
 
-def note_toctree(env: BuildEnvironment, docname: str, toctreenode: addnodes.toctree) -> None:
+def note_toctree(
+    env: BuildEnvironment, docname: str, toctreenode: addnodes.toctree
+) -> None:
     """Note a TOC tree directive in a document and gather information about
     file relations from it.
     """
@@ -87,9 +89,7 @@ def global_toctree_for_doc(
         )
         for toctree_node in env.master_doctree.findall(addnodes.toctree)
     )
-    toctrees = [
-        toctree for toctree in resolved if toctree is not None
-    ]
+    toctrees = [toctree for toctree in resolved if toctree is not None]
 
     if not toctrees:
         return None
@@ -100,9 +100,16 @@ def global_toctree_for_doc(
 
 
 def _resolve_toctree(
-    env: BuildEnvironment, docname: str, builder: Builder, toctree: addnodes.toctree, *,
-    prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-    collapse: bool = False, includehidden: bool = False,
+    env: BuildEnvironment,
+    docname: str,
+    builder: Builder,
+    toctree: addnodes.toctree,
+    *,
+    prune: bool = True,
+    maxdepth: int = 0,
+    titles_only: bool = False,
+    collapse: bool = False,
+    includehidden: bool = False,
 ) -> Element | None:
     """Resolve a *toctree* node into individual bullet lists with titles
     as items, returning None (if no containing titles are found) or
@@ -178,9 +185,13 @@ def _resolve_toctree(
 
     # prune the tree to maxdepth, also set toc depth and current classes
     _toctree_add_classes(newnode, 1, docname)
-    newnode = _toctree_copy(newnode, 1, maxdepth if prune else 0, collapse, builder.tags)
+    newnode = _toctree_copy(
+        newnode, 1, maxdepth if prune else 0, collapse, builder.tags
+    )
 
-    if isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0:  # No titles found
+    if (
+        isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0
+    ):  # No titles found
         return None
 
     # set the target paths in the toctrees (they are not known at TOC
@@ -208,11 +219,20 @@ def _entries_from_toctree(
 ) -> list[Element]:
     """Return TOC entries for a toctree node."""
     entries: list[Element] = []
-    for (title, ref) in toctreenode['entries']:
+    for title, ref in toctreenode['entries']:
         try:
             toc, refdoc = _toctree_entry(
-                title, ref, env, prune, collapse, tags, toctree_ancestors,
-                included, excluded, toctreenode, parents,
+                title,
+                ref,
+                env,
+                prune,
+                collapse,
+                tags,
+                toctree_ancestors,
+                included,
+                excluded,
+                toctreenode,
+                parents,
             )
         except LookupError:
             continue
@@ -294,10 +314,14 @@ def _toctree_entry(
             toc = _toctree_generated_entry(title, ref)
         else:
             if ref in parents:
-                logger.warning(__('circular toctree references '
-                                  'detected, ignoring: %s <- %s'),
-                               ref, ' <- '.join(parents),
-                               location=ref, type='toc', subtype='circular')
+                logger.warning(
+                    __('circular toctree references ' 'detected, ignoring: %s <- %s'),
+                    ref,
+                    ' <- '.join(parents),
+                    location=ref,
+                    type='toc',
+                    subtype='circular',
+                )
                 msg = 'circular reference'
                 raise LookupError(msg)
 
@@ -314,9 +338,16 @@ def _toctree_entry(
 
         if not toc.children:
             # empty toc means: no titles will show up in the toctree
-            logger.warning(__('toctree contains reference to document %r that '
-                              "doesn't have a title: no link will be generated"),
-                           ref, location=toctreenode, type='toc', subtype='no_title')
+            logger.warning(
+                __(
+                    'toctree contains reference to document %r that '
+                    "doesn't have a title: no link will be generated"
+                ),
+                ref,
+                location=toctreenode,
+                type='toc',
+                subtype='no_title',
+            )
     except KeyError:
         # this is raised if the included file does not exist
         ref_path = str(env.doc2path(ref, False))
@@ -335,9 +366,9 @@ def _toctree_entry(
 def _toctree_url_entry(title: str, ref: str) -> nodes.bullet_list:
     if title is None:
         title = ref
-    reference = nodes.reference('', '', internal=False,
-                                refuri=ref, anchorname='',
-                                *[nodes.Text(title)])
+    reference = nodes.reference(
+        '', '', internal=False, refuri=ref, anchorname='', *[nodes.Text(title)]
+    )
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     toc = nodes.bullet_list('', item)
@@ -345,16 +376,17 @@ def _toctree_url_entry(title: str, ref: str) -> nodes.bullet_list:
 
 
 def _toctree_self_entry(
-    title: str, ref: str, titles: dict[str, nodes.title],
+    title: str,
+    ref: str,
+    titles: dict[str, nodes.title],
 ) -> nodes.bullet_list:
     # 'self' refers to the document from which this
     # toctree originates
     if not title:
         title = clean_astext(titles[ref])
-    reference = nodes.reference('', '', internal=True,
-                                refuri=ref,
-                                anchorname='',
-                                *[nodes.Text(title)])
+    reference = nodes.reference(
+        '', '', internal=True, refuri=ref, anchorname='', *[nodes.Text(title)]
+    )
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     # don't show subitems
@@ -368,8 +400,7 @@ def _toctree_generated_entry(title: str, ref: str) -> nodes.bullet_list:
     docname, sectionname = StandardDomain._virtual_doc_names[ref]
     if not title:
         title = sectionname
-    reference = nodes.reference('', title, internal=True,
-                                refuri=docname, anchorname='')
+    reference = nodes.reference('', title, internal=True, refuri=docname, anchorname='')
     para = addnodes.compact_paragraph('', '', reference)
     item = nodes.list_item('', para)
     # don't show subitems
@@ -434,11 +465,13 @@ def _toctree_add_classes(node: Element, depth: int, docname: str) -> None:
 ET = TypeVar('ET', bound=Element)
 
 
-def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tags) -> ET:
+def _toctree_copy(
+    node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tags
+) -> ET:
     """Utility: Cut and deep-copy a TOC at a specified depth."""
-    keep_bullet_list_sub_nodes = (depth <= 1
-                                  or ((depth <= maxdepth or maxdepth <= 0)
-                                      and (not collapse or 'iscurrent' in node)))
+    keep_bullet_list_sub_nodes = depth <= 1 or (
+        (depth <= maxdepth or maxdepth <= 0) and (not collapse or 'iscurrent' in node)
+    )
 
     copy = node.copy()
     for subnode in node.children:
@@ -459,9 +492,15 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
             # only keep children if the only node matches the tags
             if _only_node_keep_children(subnode, tags):
                 for child in subnode.children:
-                    copy.append(_toctree_copy(
-                        child, depth, maxdepth, collapse, tags,  # type: ignore[type-var]
-                    ))
+                    copy.append(
+                        _toctree_copy(
+                            child,
+                            depth,
+                            maxdepth,
+                            collapse,
+                            tags,  # type: ignore[type-var]
+                        )
+                    )
         elif isinstance(subnode, nodes.reference | nodes.title):
             # deep copy references and captions
             sub_node_copy = subnode.copy()
@@ -476,7 +515,8 @@ def _toctree_copy(node: ET, depth: int, maxdepth: int, collapse: bool, tags: Tag
 
 
 def _get_toctree_ancestors(
-    toctree_includes: dict[str, list[str]], docname: str,
+    toctree_includes: dict[str, list[str]],
+    docname: str,
 ) -> Set[str]:
     parent: dict[str, str] = {}
     for p, children in toctree_includes.items():
@@ -497,11 +537,22 @@ def __init__(self, env: BuildEnvironment) -> None:
     def note(self, docname: str, toctreenode: addnodes.toctree) -> None:
         note_toctree(self.env, docname, toctreenode)
 
-    def resolve(self, docname: str, builder: Builder, toctree: addnodes.toctree,
-                prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-                collapse: bool = False, includehidden: bool = False) -> Element | None:
+    def resolve(
+        self,
+        docname: str,
+        builder: Builder,
+        toctree: addnodes.toctree,
+        prune: bool = True,
+        maxdepth: int = 0,
+        titles_only: bool = False,
+        collapse: bool = False,
+        includehidden: bool = False,
+    ) -> Element | None:
         return _resolve_toctree(
-            self.env, docname, builder, toctree,
+            self.env,
+            docname,
+            builder,
+            toctree,
             prune=prune,
             maxdepth=maxdepth,
             titles_only=titles_only,
@@ -516,6 +567,12 @@ def get_toc_for(self, docname: str, builder: Builder) -> Node:
         return document_toc(self.env, docname, self.env.app.builder.tags)
 
     def get_toctree_for(
-        self, docname: str, builder: Builder, collapse: bool, **kwargs: Any,
+        self,
+        docname: str,
+        builder: Builder,
+        collapse: bool,
+        **kwargs: Any,
     ) -> Element | None:
-        return global_toctree_for_doc(self.env, docname, builder, collapse=collapse, **kwargs)
+        return global_toctree_for_doc(
+            self.env, docname, builder, collapse=collapse, **kwargs
+        )
diff --git a/sphinx/environment/collectors/__init__.py b/sphinx/environment/collectors/__init__.py
index 52b5a60b4e2..6bb62fc42c1 100644
--- a/sphinx/environment/collectors/__init__.py
+++ b/sphinx/environment/collectors/__init__.py
@@ -29,10 +29,10 @@ class EnvironmentCollector:
     def enable(self, app: Sphinx) -> None:
         assert self.listener_ids is None
         self.listener_ids = {
-            'doctree-read':     app.connect('doctree-read', self.process_doc),
-            'env-merge-info':   app.connect('env-merge-info', self.merge_other),
-            'env-purge-doc':    app.connect('env-purge-doc', self.clear_doc),
-            'env-get-updated':  app.connect('env-get-updated', self.get_updated_docs),
+            'doctree-read': app.connect('doctree-read', self.process_doc),
+            'env-merge-info': app.connect('env-merge-info', self.merge_other),
+            'env-purge-doc': app.connect('env-purge-doc', self.clear_doc),
+            'env-get-updated': app.connect('env-get-updated', self.get_updated_docs),
             'env-get-outdated': app.connect('env-get-outdated', self.get_outdated_docs),
         }
 
@@ -51,8 +51,13 @@ def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         """
         raise NotImplementedError
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         """Merge in specified data regarding docnames from a different `BuildEnvironment`
         object which coming from a subprocess in parallel builds.
 
@@ -78,8 +83,14 @@ def get_updated_docs(self, app: Sphinx, env: BuildEnvironment) -> list[str]:
         """
         return []
 
-    def get_outdated_docs(self, app: Sphinx, env: BuildEnvironment,
-                          added: set[str], changed: set[str], removed: set[str]) -> list[str]:
+    def get_outdated_docs(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        added: set[str],
+        changed: set[str],
+        removed: set[str],
+    ) -> list[str]:
         """Return a list of docnames to re-read.
 
         This method is called before reading the documents.
diff --git a/sphinx/environment/collectors/asset.py b/sphinx/environment/collectors/asset.py
index 368e4773290..5096a9d1a68 100644
--- a/sphinx/environment/collectors/asset.py
+++ b/sphinx/environment/collectors/asset.py
@@ -33,8 +33,13 @@ class ImageCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.images.purge_doc(docname)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         env.images.merge_other(docnames, other.images)
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
@@ -86,17 +91,26 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
             for imgpath in candidates.values():
                 app.env.dependencies[docname].add(imgpath)
                 if not os.access(path.join(app.srcdir, imgpath), os.R_OK):
-                    logger.warning(__('image file not readable: %s'), imgpath,
-                                   location=node, type='image', subtype='not_readable')
+                    logger.warning(
+                        __('image file not readable: %s'),
+                        imgpath,
+                        location=node,
+                        type='image',
+                        subtype='not_readable',
+                    )
                     continue
                 app.env.images.add_file(docname, imgpath)
 
-    def collect_candidates(self, env: BuildEnvironment, imgpath: str,
-                           candidates: dict[str, str], node: Node) -> None:
+    def collect_candidates(
+        self,
+        env: BuildEnvironment,
+        imgpath: str,
+        candidates: dict[str, str],
+        node: Node,
+    ) -> None:
         globbed: dict[str, list[str]] = {}
         for filename in glob(imgpath):
-            new_imgpath = relative_path(path.join(env.srcdir, 'dummy'),
-                                        filename)
+            new_imgpath = relative_path(path.join(env.srcdir, 'dummy'), filename)
             try:
                 mimetype = guess_mimetype(filename)
                 if mimetype is None:
@@ -105,8 +119,14 @@ def collect_candidates(self, env: BuildEnvironment, imgpath: str,
                 if mimetype not in candidates:
                     globbed.setdefault(mimetype, []).append(new_imgpath)
             except OSError as err:
-                logger.warning(__('image file %s not readable: %s'), filename, err,
-                               location=node, type='image', subtype='not_readable')
+                logger.warning(
+                    __('image file %s not readable: %s'),
+                    filename,
+                    err,
+                    location=node,
+                    type='image',
+                    subtype='not_readable',
+                )
         for key, files in globbed.items():
             candidates[key] = min(files, key=len)  # select by similarity
 
@@ -117,8 +137,13 @@ class DownloadFileCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.dlfiles.purge_doc(docname)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         env.dlfiles.merge_other(docnames, other.dlfiles)
 
     def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
@@ -131,10 +156,17 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
                 rel_filename, filename = app.env.relfn2path(targetname, app.env.docname)
                 app.env.dependencies[app.env.docname].add(rel_filename)
                 if not os.access(filename, os.R_OK):
-                    logger.warning(__('download file not readable: %s'), filename,
-                                   location=node, type='download', subtype='not_readable')
+                    logger.warning(
+                        __('download file not readable: %s'),
+                        filename,
+                        location=node,
+                        type='download',
+                        subtype='not_readable',
+                    )
                     continue
-                node['filename'] = app.env.dlfiles.add_file(app.env.docname, rel_filename)
+                node['filename'] = app.env.dlfiles.add_file(
+                    app.env.docname, rel_filename
+                )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
diff --git a/sphinx/environment/collectors/dependencies.py b/sphinx/environment/collectors/dependencies.py
index 33b54b824a8..46fbf323609 100644
--- a/sphinx/environment/collectors/dependencies.py
+++ b/sphinx/environment/collectors/dependencies.py
@@ -25,8 +25,13 @@ class DependenciesCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.dependencies.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             if docname in other.dependencies:
                 env.dependencies[docname] = other.dependencies[docname]
@@ -43,8 +48,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
             # one relative to the srcdir
             if isinstance(dep, bytes):
                 dep = dep.decode(fs_encoding)
-            relpath = relative_path(frompath,
-                                    path.normpath(path.join(cwd, dep)))
+            relpath = relative_path(frompath, path.normpath(path.join(cwd, dep)))
             app.env.dependencies[app.env.docname].add(relpath)
 
 
diff --git a/sphinx/environment/collectors/metadata.py b/sphinx/environment/collectors/metadata.py
index bef35119e3a..aadc6af1613 100644
--- a/sphinx/environment/collectors/metadata.py
+++ b/sphinx/environment/collectors/metadata.py
@@ -20,8 +20,13 @@ class MetadataCollector(EnvironmentCollector):
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.metadata.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             env.metadata[docname] = other.metadata[docname]
 
diff --git a/sphinx/environment/collectors/title.py b/sphinx/environment/collectors/title.py
index 76e3f0379f5..830c8702cf3 100644
--- a/sphinx/environment/collectors/title.py
+++ b/sphinx/environment/collectors/title.py
@@ -22,8 +22,13 @@ def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.titles.pop(docname, None)
         env.longtitles.pop(docname, None)
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment,
-                    docnames: set[str], other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             env.titles[docname] = other.titles[docname]
             env.longtitles[docname] = other.longtitles[docname]
diff --git a/sphinx/environment/collectors/toctree.py b/sphinx/environment/collectors/toctree.py
index f004fc6820a..1de7b2473eb 100644
--- a/sphinx/environment/collectors/toctree.py
+++ b/sphinx/environment/collectors/toctree.py
@@ -43,8 +43,13 @@ def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
             if not fnset:
                 del env.files_to_rebuild[subfn]
 
-    def merge_other(self, app: Sphinx, env: BuildEnvironment, docnames: set[str],
-                    other: BuildEnvironment) -> None:
+    def merge_other(
+        self,
+        app: Sphinx,
+        env: BuildEnvironment,
+        docnames: set[str],
+        other: BuildEnvironment,
+    ) -> None:
         for docname in docnames:
             env.tocs[docname] = other.tocs[docname]
             env.toc_num_entries[docname] = other.toc_num_entries[docname]
@@ -84,8 +89,13 @@ def build_toc(
                     # make these nodes:
                     # list_item -> compact_paragraph -> reference
                     reference = nodes.reference(
-                        '', '', internal=True, refuri=docname,
-                        anchorname=anchorname, *nodetext)
+                        '',
+                        '',
+                        internal=True,
+                        refuri=docname,
+                        anchorname=anchorname,
+                        *nodetext,
+                    )
                     para = addnodes.compact_paragraph('', '', reference)
                     item: Element = nodes.list_item('', para)
                     sub_item = build_toc(sectionnode, depth + 1)
@@ -136,15 +146,23 @@ def build_toc(
                                 anchorname = _make_anchor_name(ids, numentries)
 
                                 reference = nodes.reference(
-                                    '', '', nodes.literal('', sig_node['_toc_name']),
-                                    internal=True, refuri=docname, anchorname=anchorname)
-                                para = addnodes.compact_paragraph('', '', reference,
-                                                                  skip_section_number=True)
+                                    '',
+                                    '',
+                                    nodes.literal('', sig_node['_toc_name']),
+                                    internal=True,
+                                    refuri=docname,
+                                    anchorname=anchorname,
+                                )
+                                para = addnodes.compact_paragraph(
+                                    '', '', reference, skip_section_number=True
+                                )
                                 entry = nodes.list_item('', para)
 
                                 # Find parent node
                                 parent = sig_node.parent
-                                while parent not in memo_parents and parent != sectionnode:
+                                while (
+                                    parent not in memo_parents and parent != sectionnode
+                                ):
                                     parent = parent.parent
                                 # Note, it may both be the limit and in memo_parents,
                                 # prefer memo_parents, so we get the nesting.
@@ -231,14 +249,21 @@ def _walk_toc(
         def _walk_toctree(toctreenode: addnodes.toctree, depth: int) -> None:
             if depth == 0:
                 return
-            for (_title, ref) in toctreenode['entries']:
+            for _title, ref in toctreenode['entries']:
                 if url_re.match(ref) or ref == 'self':
                     # don't mess with those
                     continue
                 if ref in assigned:
-                    logger.warning(__('%s is already assigned section numbers '
-                                      '(nested numbered toctree?)'), ref,
-                                   location=toctreenode, type='toc', subtype='secnum')
+                    logger.warning(
+                        __(
+                            '%s is already assigned section numbers '
+                            '(nested numbered toctree?)'
+                        ),
+                        ref,
+                        location=toctreenode,
+                        type='toc',
+                        subtype='secnum',
+                    )
                 elif ref in env.tocs:
                     secnums: dict[str, tuple[int, ...]] = {}
                     env.toc_secnumbers[ref] = secnums
@@ -273,7 +298,9 @@ def assign_figure_numbers(self, env: BuildEnvironment) -> list[str]:
         def get_figtype(node: Node) -> str | None:
             for domain in env.domains.sorted():
                 figtype = domain.get_enumerable_node_type(node)
-                if isinstance(domain, StandardDomain) and not domain.get_numfig_title(node):
+                if isinstance(domain, StandardDomain) and not domain.get_numfig_title(
+                    node
+                ):
                     # Skip if uncaptioned node
                     continue
 
@@ -292,22 +319,27 @@ def get_section_number(docname: str, section: nodes.section) -> tuple[int, ...]:
 
             return secnum or ()
 
-        def get_next_fignumber(figtype: str, secnum: tuple[int, ...]) -> tuple[int, ...]:
+        def get_next_fignumber(
+            figtype: str, secnum: tuple[int, ...]
+        ) -> tuple[int, ...]:
             counter = fignum_counter.setdefault(figtype, {})
 
-            secnum = secnum[:env.config.numfig_secnum_depth]
+            secnum = secnum[: env.config.numfig_secnum_depth]
             counter[secnum] = counter.get(secnum, 0) + 1
             return (*secnum, counter[secnum])
 
-        def register_fignumber(docname: str, secnum: tuple[int, ...],
-                               figtype: str, fignode: Element) -> None:
+        def register_fignumber(
+            docname: str, secnum: tuple[int, ...], figtype: str, fignode: Element
+        ) -> None:
             env.toc_fignumbers.setdefault(docname, {})
             fignumbers = env.toc_fignumbers[docname].setdefault(figtype, {})
             figure_id = fignode['ids'][0]
 
             fignumbers[figure_id] = get_next_fignumber(figtype, secnum)
 
-        def _walk_doctree(docname: str, doctree: Element, secnum: tuple[int, ...]) -> None:
+        def _walk_doctree(
+            docname: str, doctree: Element, secnum: tuple[int, ...]
+        ) -> None:
             nonlocal generated_docnames
             for subnode in doctree.children:
                 if isinstance(subnode, nodes.section):

From a0fe15c00d0cf8c0ed4a1208bdf6577bb05c2800 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 16:55:39 +0100
Subject: [PATCH 26/29] Report GIL status in pytest

---
 tests/conftest.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/conftest.py b/tests/conftest.py
index a9ef8e7c92c..bf8b3eb2ebe 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -49,6 +49,8 @@ def rootdir() -> Path:
 
 def pytest_report_header(config: pytest.Config) -> str:
     header = f'libraries: Sphinx-{sphinx.__display_version__}, docutils-{docutils.__version__}'
+    if sys.version_info[:2] >= (3, 13):
+        header += f'\nGIL enabled?: {sys._is_gil_enabled()}'
     if hasattr(config, '_tmp_path_factory'):
         header += f'\nbase tmp_path: {config._tmp_path_factory.getbasetemp()}'
     return header

From a404f3e66c6ecbd0e57670c454335243006785e6 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 17:08:20 +0100
Subject: [PATCH 27/29] Enable automatic formatting for ``sphinx/testing/``
 (#12969)

---
 .ruff.toml                 |  1 -
 sphinx/testing/fixtures.py |  3 +-
 sphinx/testing/path.py     | 10 +++---
 sphinx/testing/util.py     | 73 ++++++++++++++++++++++++--------------
 4 files changed, 55 insertions(+), 32 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index b142fcbd60f..5d38a3a0170 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -476,7 +476,6 @@ exclude = [
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
     "sphinx/registry.py",
-    "sphinx/testing/*",
     "sphinx/transforms/*",
     "sphinx/writers/*",
 ]
diff --git a/sphinx/testing/fixtures.py b/sphinx/testing/fixtures.py
index 03e38e85e86..6f1c29cdba2 100644
--- a/sphinx/testing/fixtures.py
+++ b/sphinx/testing/fixtures.py
@@ -86,7 +86,7 @@ def app_params(
     kwargs: dict[str, Any] = {}
 
     # to avoid stacking positional args
-    for info in reversed(list(request.node.iter_markers("sphinx"))):
+    for info in reversed(list(request.node.iter_markers('sphinx'))):
         pargs |= dict(enumerate(info.args))
         kwargs.update(info.kwargs)
 
@@ -203,6 +203,7 @@ def make(*args: Any, **kwargs: Any) -> SphinxTestApp:
             app_ = SphinxTestApp(*args, **kwargs)
         apps.append(app_)
         return app_
+
     yield make
 
     sys.path[:] = syspath
diff --git a/sphinx/testing/path.py b/sphinx/testing/path.py
index 49f0ffa6005..9792dcb7479 100644
--- a/sphinx/testing/path.py
+++ b/sphinx/testing/path.py
@@ -12,9 +12,11 @@
     import builtins
     from collections.abc import Callable
 
-warnings.warn("'sphinx.testing.path' is deprecated. "
-              "Use 'os.path' or 'pathlib' instead.",
-              RemovedInSphinx90Warning, stacklevel=2)
+warnings.warn(
+    "'sphinx.testing.path' is deprecated. " "Use 'os.path' or 'pathlib' instead.",
+    RemovedInSphinx90Warning,
+    stacklevel=2,
+)
 
 FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding()
 
@@ -86,7 +88,7 @@ def ismount(self) -> bool:
     def rmtree(
         self,
         ignore_errors: bool = False,
-        onerror:  Callable[[Callable[..., Any], str, Any], object] | None = None,
+        onerror: Callable[[Callable[..., Any], str, Any], object] | None = None,
     ) -> None:
         """
         Removes the file or directory and any files or directories it may
diff --git a/sphinx/testing/util.py b/sphinx/testing/util.py
index f99442eb004..4d221133ffb 100644
--- a/sphinx/testing/util.py
+++ b/sphinx/testing/util.py
@@ -29,7 +29,7 @@
     from docutils.nodes import Node
 
 
-def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) -> None:
+def assert_node(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any) -> None:
     if cls:
         if isinstance(cls, list):
             assert_node(node, cls[0], xpath=xpath, **kwargs)
@@ -37,36 +37,43 @@ def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) ->
                 if isinstance(cls[1], tuple):
                     assert_node(node, cls[1], xpath=xpath, **kwargs)
                 else:
-                    assert isinstance(node, nodes.Element), \
-                        'The node%s does not have any children' % xpath
-                    assert len(node) == 1, \
-                        'The node%s has %d child nodes, not one' % (xpath, len(node))
-                    assert_node(node[0], cls[1:], xpath=xpath + "[0]", **kwargs)
+                    assert (
+                        isinstance(node, nodes.Element)
+                    ), f'The node{xpath} does not have any children'  # fmt: skip
+                    assert (
+                        len(node) == 1
+                    ), f'The node{xpath} has {len(node)} child nodes, not one'
+                    assert_node(node[0], cls[1:], xpath=xpath + '[0]', **kwargs)
         elif isinstance(cls, tuple):
-            assert isinstance(node, list | nodes.Element), \
-                'The node%s does not have any items' % xpath
-            assert len(node) == len(cls), \
-                'The node%s has %d child nodes, not %r' % (xpath, len(node), len(cls))
+            assert (
+                isinstance(node, list | nodes.Element)
+            ), f'The node{xpath} does not have any items'  # fmt: skip
+            assert (
+                len(node) == len(cls)
+            ), f'The node{xpath} has {len(node)} child nodes, not {len(cls)!r}'  # fmt: skip
             for i, nodecls in enumerate(cls):
-                path = xpath + "[%d]" % i
+                path = xpath + f'[{i}]'
                 assert_node(node[i], nodecls, xpath=path, **kwargs)
         elif isinstance(cls, str):
             assert node == cls, f'The node {xpath!r} is not {cls!r}: {node!r}'
         else:
-            assert isinstance(node, cls), \
-                f'The node{xpath} is not subclass of {cls!r}: {node!r}'
+            assert (
+                isinstance(node, cls)
+            ), f'The node{xpath} is not subclass of {cls!r}: {node!r}'  # fmt: skip
 
     if kwargs:
-        assert isinstance(node, nodes.Element), \
-            'The node%s does not have any attributes' % xpath
+        assert (
+            isinstance(node, nodes.Element)
+        ), f'The node{xpath} does not have any attributes'  # fmt: skip
 
         for key, value in kwargs.items():
             if key not in node:
                 if (key := key.replace('_', '-')) not in node:
                     msg = f'The node{xpath} does not have {key!r} attribute: {node!r}'
                     raise AssertionError(msg)
-            assert node[key] == value, \
-                f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
+            assert (
+                node[key] == value
+            ), f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
 
 
 # keep this to restrict the API usage and to have a correct return type
@@ -138,7 +145,7 @@ def __init__(
             # but allow the stream to be /dev/null by passing verbosity=-1
             status = None if quiet else StringIO()
         elif not isinstance(status, StringIO):
-            err = "%r must be an io.StringIO object, got: %s" % ('status', type(status))
+            err = f"'status' must be an io.StringIO object, got: {type(status)}"
             raise TypeError(err)
 
         if warning is None:
@@ -146,7 +153,7 @@ def __init__(
             # but allow the stream to be /dev/null by passing verbosity=-1
             warning = None if quiet else StringIO()
         elif not isinstance(warning, StringIO):
-            err = '%r must be an io.StringIO object, got: %s' % ('warning', type(warning))
+            err = f"'warning' must be an io.StringIO object, got: {type(warning)}"
             raise TypeError(err)
 
         self.docutils_conf_path = srcdir / 'docutils.conf'
@@ -170,11 +177,21 @@ def __init__(
 
         try:
             super().__init__(
-                srcdir, confdir, outdir, doctreedir, buildername,
-                confoverrides=confoverrides, status=status, warning=warning,
-                freshenv=freshenv, warningiserror=warningiserror, tags=tags,
-                verbosity=verbosity, parallel=parallel,
-                pdb=pdb, exception_on_warning=exception_on_warning,
+                srcdir,
+                confdir,
+                outdir,
+                doctreedir,
+                buildername,
+                confoverrides=confoverrides,
+                status=status,
+                warning=warning,
+                freshenv=freshenv,
+                warningiserror=warningiserror,
+                tags=tags,
+                verbosity=verbosity,
+                parallel=parallel,
+                pdb=pdb,
+                exception_on_warning=exception_on_warning,
             )
         except Exception:
             self.cleanup()
@@ -213,7 +230,9 @@ def cleanup(self, doctrees: bool = False) -> None:
     def __repr__(self) -> str:
         return f'<{self.__class__.__name__} buildername={self._builder_name!r}>'
 
-    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+    def build(
+        self, force_all: bool = False, filenames: list[str] | None = None
+    ) -> None:
         self.env._pickled_doctree_cache.clear()
         super().build(force_all, filenames)
 
@@ -225,7 +244,9 @@ class SphinxTestAppWrapperForSkipBuilding(SphinxTestApp):
     if it has already been built and there are any output files.
     """
 
-    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+    def build(
+        self, force_all: bool = False, filenames: list[str] | None = None
+    ) -> None:
         if not os.listdir(self.outdir):
             # if listdir is empty, do build.
             super().build(force_all, filenames)

From 3a066f2bbc2500485cf9ad50e4bdedcc1e157882 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 17:08:30 +0100
Subject: [PATCH 28/29] Enable automatic formatting for
 ``sphinx/ext/intersphinx/`` (#12970)

---
 .ruff.toml                         |   1 -
 sphinx/ext/intersphinx/_cli.py     |  10 +-
 sphinx/ext/intersphinx/_load.py    |  74 ++++++---
 sphinx/ext/intersphinx/_resolve.py | 239 ++++++++++++++++++++---------
 sphinx/ext/intersphinx/_shared.py  |  12 +-
 5 files changed, 229 insertions(+), 107 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 5d38a3a0170..03ade239ca1 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -468,7 +468,6 @@ exclude = [
     "sphinx/ext/imgconverter.py",
     "sphinx/ext/imgmath.py",
     "sphinx/ext/inheritance_diagram.py",
-    "sphinx/ext/intersphinx/*",
     "sphinx/ext/linkcode.py",
     "sphinx/ext/mathjax.py",
     "sphinx/ext/napoleon/__init__.py",
diff --git a/sphinx/ext/intersphinx/_cli.py b/sphinx/ext/intersphinx/_cli.py
index 25ec6ca7c8c..04ac2876291 100644
--- a/sphinx/ext/intersphinx/_cli.py
+++ b/sphinx/ext/intersphinx/_cli.py
@@ -10,9 +10,11 @@
 def inspect_main(argv: list[str], /) -> int:
     """Debug functionality to print out an inventory"""
     if len(argv) < 1:
-        print('Print out an inventory file.\n'
-              'Error: must specify local path or URL to an inventory file.',
-              file=sys.stderr)
+        print(
+            'Print out an inventory file.\n'
+            'Error: must specify local path or URL to an inventory file.',
+            file=sys.stderr,
+        )
         return 1
 
     class MockConfig:
@@ -27,7 +29,7 @@ class MockConfig:
             target_uri='',
             inv_location=filename,
             config=MockConfig(),  # type: ignore[arg-type]
-            srcdir=''  # type: ignore[arg-type]
+            srcdir='',  # type: ignore[arg-type]
         )
         for key in sorted(inv_data or {}):
             print(key)
diff --git a/sphinx/ext/intersphinx/_load.py b/sphinx/ext/intersphinx/_load.py
index 53324f7103f..b891d0d999a 100644
--- a/sphinx/ext/intersphinx/_load.py
+++ b/sphinx/ext/intersphinx/_load.py
@@ -89,8 +89,10 @@ def validate_intersphinx_mapping(app: Sphinx, config: Config) -> None:
         # ensure target URIs are non-empty and unique
         if not uri or not isinstance(uri, str):
             errors += 1
-            msg = __('Invalid target URI value `%r` in intersphinx_mapping[%r][0]. '
-                     'Target URIs must be unique non-empty strings.')
+            msg = __(
+                'Invalid target URI value `%r` in intersphinx_mapping[%r][0]. '
+                'Target URIs must be unique non-empty strings.'
+            )
             LOGGER.error(msg, uri, name)
             del config.intersphinx_mapping[name]
             continue
@@ -105,9 +107,12 @@ def validate_intersphinx_mapping(app: Sphinx, config: Config) -> None:
             continue
         seen[uri] = name
 
+        if not isinstance(inv, tuple | list):
+            inv = (inv,)
+
         # ensure inventory locations are None or non-empty
         targets: list[InventoryLocation] = []
-        for target in (inv if isinstance(inv, (tuple | list)) else (inv,)):
+        for target in inv:
             if target is None or target and isinstance(target, str):
                 targets.append(target)
             else:
@@ -143,9 +148,13 @@ def load_mappings(app: Sphinx) -> None:
     projects = []
     for name, (uri, locations) in intersphinx_mapping.values():
         try:
-            project = _IntersphinxProject(name=name, target_uri=uri, locations=locations)
+            project = _IntersphinxProject(
+                name=name, target_uri=uri, locations=locations
+            )
         except ValueError as err:
-            msg = __('An invalid intersphinx_mapping entry was added after normalisation.')
+            msg = __(
+                'An invalid intersphinx_mapping entry was added after normalisation.'
+            )
             raise ConfigError(msg) from err
         else:
             projects.append(project)
@@ -223,8 +232,11 @@ def _fetch_inventory_group(
             or project.target_uri not in cache
             or cache[project.target_uri][1] < cache_time
         ):
-            LOGGER.info(__("loading intersphinx inventory '%s' from %s ..."),
-                        project.name, _get_safe_url(inv))
+            LOGGER.info(
+                __("loading intersphinx inventory '%s' from %s ..."),
+                project.name,
+                _get_safe_url(inv),
+            )
 
             try:
                 invdata = _fetch_inventory(
@@ -245,14 +257,21 @@ def _fetch_inventory_group(
     if not failures:
         pass
     elif len(failures) < len(project.locations):
-        LOGGER.info(__('encountered some issues with some of the inventories,'
-                       ' but they had working alternatives:'))
+        LOGGER.info(
+            __(
+                'encountered some issues with some of the inventories,'
+                ' but they had working alternatives:'
+            )
+        )
         for fail in failures:
             LOGGER.info(*fail)
     else:
         issues = '\n'.join(f[0] % f[1:] for f in failures)
-        LOGGER.warning(__('failed to reach any of the inventories '
-                          'with the following issues:') + '\n' + issues)
+        LOGGER.warning(
+            __('failed to reach any of the inventories ' 'with the following issues:')
+            + '\n'
+            + issues
+        )
     return updated
 
 
@@ -267,7 +286,7 @@ def fetch_inventory(app: Sphinx, uri: InventoryURI, inv: str) -> Inventory:
 
 
 def _fetch_inventory(
-    *, target_uri: InventoryURI, inv_location: str, config: Config, srcdir: Path,
+    *, target_uri: InventoryURI, inv_location: str, config: Config, srcdir: Path
 ) -> Inventory:
     """Fetch, parse and return an intersphinx inventory file."""
     # both *target_uri* (base URI of the links to generate)
@@ -282,8 +301,12 @@ def _fetch_inventory(
         else:
             f = open(path.join(srcdir, inv_location), 'rb')  # NoQA: SIM115
     except Exception as err:
-        err.args = ('intersphinx inventory %r not fetchable due to %s: %s',
-                    inv_location, err.__class__, str(err))
+        err.args = (
+            'intersphinx inventory %r not fetchable due to %s: %s',
+            inv_location,
+            err.__class__,
+            str(err),
+        )
         raise
     try:
         if hasattr(f, 'url'):
@@ -295,17 +318,22 @@ def _fetch_inventory(
                 if target_uri in {
                     inv_location,
                     path.dirname(inv_location),
-                    path.dirname(inv_location) + '/'
+                    path.dirname(inv_location) + '/',
                 }:
                     target_uri = path.dirname(new_inv_location)
         with f:
             try:
                 invdata = InventoryFile.load(f, target_uri, posixpath.join)
             except ValueError as exc:
-                raise ValueError('unknown or unsupported inventory version: %r' % exc) from exc
+                msg = f'unknown or unsupported inventory version: {exc!r}'
+                raise ValueError(msg) from exc
     except Exception as err:
-        err.args = ('intersphinx inventory %r not readable due to %s: %s',
-                    inv_location, err.__class__.__name__, str(err))
+        err.args = (
+            'intersphinx inventory %r not readable due to %s: %s',
+            inv_location,
+            err.__class__.__name__,
+            str(err),
+        )
         raise
     else:
         return invdata
@@ -373,9 +401,13 @@ def _read_from_url(url: str, *, config: Config) -> HTTPResponse:
     :return: data read from resource described by *url*
     :rtype: ``file``-like object
     """
-    r = requests.get(url, stream=True, timeout=config.intersphinx_timeout,
-                     _user_agent=config.user_agent,
-                     _tls_info=(config.tls_verify, config.tls_cacerts))
+    r = requests.get(
+        url,
+        stream=True,
+        timeout=config.intersphinx_timeout,
+        _user_agent=config.user_agent,
+        _tls_info=(config.tls_verify, config.tls_cacerts),
+    )
     r.raise_for_status()
 
     # For inv_location / new_inv_location
diff --git a/sphinx/ext/intersphinx/_resolve.py b/sphinx/ext/intersphinx/_resolve.py
index a816a94f257..9387d1e1096 100644
--- a/sphinx/ext/intersphinx/_resolve.py
+++ b/sphinx/ext/intersphinx/_resolve.py
@@ -32,9 +32,13 @@
     from sphinx.util.typing import Inventory, InventoryItem, RoleFunction
 
 
-def _create_element_from_result(domain: Domain, inv_name: InventoryName | None,
-                                data: InventoryItem,
-                                node: pending_xref, contnode: TextElement) -> nodes.reference:
+def _create_element_from_result(
+    domain: Domain,
+    inv_name: InventoryName | None,
+    data: InventoryItem,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference:
     proj, version, uri, dispname = data
     if '://' not in uri and node.get('refdoc'):
         # get correct path in case of subdirectories
@@ -51,8 +55,11 @@ def _create_element_from_result(domain: Domain, inv_name: InventoryName | None,
         # use whatever title was given, but strip prefix
         title = contnode.astext()
         if inv_name is not None and title.startswith(inv_name + ':'):
-            newnode.append(contnode.__class__(title[len(inv_name) + 1:],
-                                              title[len(inv_name) + 1:]))
+            newnode.append(
+                contnode.__class__(
+                    title[len(inv_name) + 1 :], title[len(inv_name) + 1 :]
+                )
+            )
         else:
             newnode.append(contnode)
     else:
@@ -62,10 +69,14 @@ def _create_element_from_result(domain: Domain, inv_name: InventoryName | None,
 
 
 def _resolve_reference_in_domain_by_target(
-        inv_name: InventoryName | None, inventory: Inventory,
-        domain: Domain, objtypes: Iterable[str],
-        target: str,
-        node: pending_xref, contnode: TextElement) -> nodes.reference | None:
+    inv_name: InventoryName | None,
+    inventory: Inventory,
+    domain: Domain,
+    objtypes: Iterable[str],
+    target: str,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
     for objtype in objtypes:
         if objtype not in inventory:
             # Continue if there's nothing of this kind in the inventory
@@ -79,19 +90,34 @@ def _resolve_reference_in_domain_by_target(
             # * 'term': https://github.com/sphinx-doc/sphinx/issues/9291
             # * 'label': https://github.com/sphinx-doc/sphinx/issues/12008
             target_lower = target.lower()
-            insensitive_matches = list(filter(lambda k: k.lower() == target_lower,
-                                              inventory[objtype].keys()))
+            insensitive_matches = list(
+                filter(lambda k: k.lower() == target_lower, inventory[objtype].keys())
+            )
             if len(insensitive_matches) > 1:
-                data_items = {inventory[objtype][match] for match in insensitive_matches}
+                data_items = {
+                    inventory[objtype][match] for match in insensitive_matches
+                }
                 inv_descriptor = inv_name or 'main_inventory'
                 if len(data_items) == 1:  # these are duplicates; relatively innocuous
-                    LOGGER.debug(__("inventory '%s': duplicate matches found for %s:%s"),
-                                 inv_descriptor, objtype, target,
-                                 type='intersphinx',  subtype='external', location=node)
+                    LOGGER.debug(
+                        __("inventory '%s': duplicate matches found for %s:%s"),
+                        inv_descriptor,
+                        objtype,
+                        target,
+                        type='intersphinx',
+                        subtype='external',
+                        location=node,
+                    )
                 else:
-                    LOGGER.warning(__("inventory '%s': multiple matches found for %s:%s"),
-                                   inv_descriptor, objtype, target,
-                                   type='intersphinx',  subtype='external', location=node)
+                    LOGGER.warning(
+                        __("inventory '%s': multiple matches found for %s:%s"),
+                        inv_descriptor,
+                        objtype,
+                        target,
+                        type='intersphinx',
+                        subtype='external',
+                        location=node,
+                    )
             if insensitive_matches:
                 data = inventory[objtype][insensitive_matches[0]]
             else:
@@ -106,12 +132,16 @@ def _resolve_reference_in_domain_by_target(
     return None
 
 
-def _resolve_reference_in_domain(env: BuildEnvironment,
-                                 inv_name: InventoryName | None, inventory: Inventory,
-                                 honor_disabled_refs: bool,
-                                 domain: Domain, objtypes: Iterable[str],
-                                 node: pending_xref, contnode: TextElement,
-                                 ) -> nodes.reference | None:
+def _resolve_reference_in_domain(
+    env: BuildEnvironment,
+    inv_name: InventoryName | None,
+    inventory: Inventory,
+    honor_disabled_refs: bool,
+    domain: Domain,
+    objtypes: Iterable[str],
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
     obj_types: dict[str, None] = {}.fromkeys(objtypes)
 
     # we adjust the object types for backwards compatibility
@@ -129,15 +159,16 @@ def _resolve_reference_in_domain(env: BuildEnvironment,
     # now that the objtypes list is complete we can remove the disabled ones
     if honor_disabled_refs:
         disabled = set(env.config.intersphinx_disabled_reftypes)
-        obj_types = {obj_type: None
-                     for obj_type in obj_types
-                     if obj_type not in disabled}
+        obj_types = {
+            obj_type: None for obj_type in obj_types if obj_type not in disabled
+        }
 
     objtypes = [*obj_types.keys()]
 
     # without qualification
-    res = _resolve_reference_in_domain_by_target(inv_name, inventory, domain, objtypes,
-                                                 node['reftarget'], node, contnode)
+    res = _resolve_reference_in_domain_by_target(
+        inv_name, inventory, domain, objtypes, node['reftarget'], node, contnode
+    )
     if res is not None:
         return res
 
@@ -145,14 +176,19 @@ def _resolve_reference_in_domain(env: BuildEnvironment,
     full_qualified_name = domain.get_full_qualified_name(node)
     if full_qualified_name is None:
         return None
-    return _resolve_reference_in_domain_by_target(inv_name, inventory, domain, objtypes,
-                                                  full_qualified_name, node, contnode)
-
-
-def _resolve_reference(env: BuildEnvironment,
-                       inv_name: InventoryName | None, inventory: Inventory,
-                       honor_disabled_refs: bool,
-                       node: pending_xref, contnode: TextElement) -> nodes.reference | None:
+    return _resolve_reference_in_domain_by_target(
+        inv_name, inventory, domain, objtypes, full_qualified_name, node, contnode
+    )
+
+
+def _resolve_reference(
+    env: BuildEnvironment,
+    inv_name: InventoryName | None,
+    inventory: Inventory,
+    honor_disabled_refs: bool,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
     # disabling should only be done if no inventory is given
     honor_disabled_refs = honor_disabled_refs and inv_name is None
     intersphinx_disabled_reftypes = env.config.intersphinx_disabled_reftypes
@@ -163,13 +199,22 @@ def _resolve_reference(env: BuildEnvironment,
     typ = node['reftype']
     if typ == 'any':
         for domain in env.domains.sorted():
-            if honor_disabled_refs and f'{domain.name}:*' in intersphinx_disabled_reftypes:
+            if (
+                honor_disabled_refs
+                and f'{domain.name}:*' in intersphinx_disabled_reftypes
+            ):
                 continue
             objtypes: Iterable[str] = domain.object_types.keys()
-            res = _resolve_reference_in_domain(env, inv_name, inventory,
-                                               honor_disabled_refs,
-                                               domain, objtypes,
-                                               node, contnode)
+            res = _resolve_reference_in_domain(
+                env,
+                inv_name,
+                inventory,
+                honor_disabled_refs,
+                domain,
+                objtypes,
+                node,
+                contnode,
+            )
             if res is not None:
                 return res
         return None
@@ -184,20 +229,28 @@ def _resolve_reference(env: BuildEnvironment,
         objtypes = domain.objtypes_for_role(typ) or ()
         if not objtypes:
             return None
-        return _resolve_reference_in_domain(env, inv_name, inventory,
-                                            honor_disabled_refs,
-                                            domain, objtypes,
-                                            node, contnode)
+        return _resolve_reference_in_domain(
+            env,
+            inv_name,
+            inventory,
+            honor_disabled_refs,
+            domain,
+            objtypes,
+            node,
+            contnode,
+        )
 
 
 def inventory_exists(env: BuildEnvironment, inv_name: InventoryName) -> bool:
     return inv_name in InventoryAdapter(env).named_inventory
 
 
-def resolve_reference_in_inventory(env: BuildEnvironment,
-                                   inv_name: InventoryName,
-                                   node: pending_xref, contnode: TextElement,
-                                   ) -> nodes.reference | None:
+def resolve_reference_in_inventory(
+    env: BuildEnvironment,
+    inv_name: InventoryName,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
     """Attempt to resolve a missing reference via intersphinx references.
 
     Resolution is tried in the given inventory with the target as is.
@@ -205,26 +258,39 @@ def resolve_reference_in_inventory(env: BuildEnvironment,
     Requires ``inventory_exists(env, inv_name)``.
     """
     assert inventory_exists(env, inv_name)
-    return _resolve_reference(env, inv_name, InventoryAdapter(env).named_inventory[inv_name],
-                              False, node, contnode)
-
-
-def resolve_reference_any_inventory(env: BuildEnvironment,
-                                    honor_disabled_refs: bool,
-                                    node: pending_xref, contnode: TextElement,
-                                    ) -> nodes.reference | None:
+    return _resolve_reference(
+        env,
+        inv_name,
+        InventoryAdapter(env).named_inventory[inv_name],
+        False,
+        node,
+        contnode,
+    )
+
+
+def resolve_reference_any_inventory(
+    env: BuildEnvironment,
+    honor_disabled_refs: bool,
+    node: pending_xref,
+    contnode: TextElement,
+) -> nodes.reference | None:
     """Attempt to resolve a missing reference via intersphinx references.
 
     Resolution is tried with the target as is in any inventory.
     """
-    return _resolve_reference(env, None, InventoryAdapter(env).main_inventory,
-                              honor_disabled_refs,
-                              node, contnode)
-
-
-def resolve_reference_detect_inventory(env: BuildEnvironment,
-                                       node: pending_xref, contnode: TextElement,
-                                       ) -> nodes.reference | None:
+    return _resolve_reference(
+        env,
+        None,
+        InventoryAdapter(env).main_inventory,
+        honor_disabled_refs,
+        node,
+        contnode,
+    )
+
+
+def resolve_reference_detect_inventory(
+    env: BuildEnvironment, node: pending_xref, contnode: TextElement
+) -> nodes.reference | None:
     """Attempt to resolve a missing reference via intersphinx references.
 
     Resolution is tried first with the target as is in any inventory.
@@ -250,8 +316,9 @@ def resolve_reference_detect_inventory(env: BuildEnvironment,
     return res_inv
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
-                      contnode: TextElement) -> nodes.reference | None:
+def missing_reference(
+    app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: TextElement
+) -> nodes.reference | None:
     """Attempt to resolve a missing reference via intersphinx references."""
     return resolve_reference_detect_inventory(env, node, contnode)
 
@@ -263,7 +330,11 @@ class IntersphinxDispatcher(CustomReSTDispatcher):
     """
 
     def role(
-        self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter,
+        self,
+        role_name: str,
+        language_module: ModuleType,
+        lineno: int,
+        reporter: Reporter,
     ) -> tuple[RoleFunction, list[system_message]]:
         if len(role_name) > 9 and role_name.startswith(('external:', 'external+')):
             return IntersphinxRole(role_name), []
@@ -461,7 +532,9 @@ def is_existent_role(self, domain_name: str, role_name: str) -> bool:
         except ExtensionError:
             return False
 
-    def invoke_role(self, role: tuple[str, str]) -> tuple[list[Node], list[system_message]]:
+    def invoke_role(
+        self, role: tuple[str, str]
+    ) -> tuple[list[Node], list[system_message]]:
         """Invoke the role described by a ``(domain, role name)`` pair."""
         _deprecation_warning(
             __name__, f'{self.__class__.__name__}.invoke_role', '', remove=(9, 0)
@@ -471,8 +544,15 @@ def invoke_role(self, role: tuple[str, str]) -> tuple[list[Node], list[system_me
             role_func = domain.role(role[1])
             assert role_func is not None
 
-            return role_func(':'.join(role), self.rawtext, self.text, self.lineno,
-                             self.inliner, self.options, self.content)
+            return role_func(
+                ':'.join(role),
+                self.rawtext,
+                self.text,
+                self.lineno,
+                self.inliner,
+                self.options,
+                self.content,
+            )
         else:
             return [], []
 
@@ -493,13 +573,20 @@ def run(self, **kwargs: Any) -> None:
             inv_name = node['inventory']
             if inv_name is not None:
                 assert inventory_exists(self.env, inv_name)
-                newnode = resolve_reference_in_inventory(self.env, inv_name, node, contnode)
+                newnode = resolve_reference_in_inventory(
+                    self.env, inv_name, node, contnode
+                )
             else:
-                newnode = resolve_reference_any_inventory(self.env, False, node, contnode)
+                newnode = resolve_reference_any_inventory(
+                    self.env, False, node, contnode
+                )
             if newnode is None:
                 typ = node['reftype']
-                msg = (__('external %s:%s reference target not found: %s') %
-                       (node['refdomain'], typ, node['reftarget']))
+                msg = __('external %s:%s reference target not found: %s') % (
+                    node['refdomain'],
+                    typ,
+                    node['reftarget'],
+                )
                 LOGGER.warning(msg, location=node, type='ref', subtype=typ)
                 node.replace_self(contnode)
             else:
diff --git a/sphinx/ext/intersphinx/_shared.py b/sphinx/ext/intersphinx/_shared.py
index 36c73786f34..44ad9562383 100644
--- a/sphinx/ext/intersphinx/_shared.py
+++ b/sphinx/ext/intersphinx/_shared.py
@@ -54,7 +54,7 @@ class _IntersphinxProject:
         'locations':  'A tuple of local or remote targets containing '
                       'the inventory data to fetch. '
                       'None indicates the default inventory file name.',
-    }
+    }  # fmt: skip
 
     def __init__(
         self,
@@ -83,10 +83,12 @@ def __init__(
         object.__setattr__(self, 'locations', tuple(locations))
 
     def __repr__(self) -> str:
-        return (f'{self.__class__.__name__}('
-                f'name={self.name!r}, '
-                f'target_uri={self.target_uri!r}, '
-                f'locations={self.locations!r})')
+        return (
+            f'{self.__class__.__name__}('
+            f'name={self.name!r}, '
+            f'target_uri={self.target_uri!r}, '
+            f'locations={self.locations!r})'
+        )
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, _IntersphinxProject):

From a6e449094a7848d4a7ec8be0601e1c4acd1d2bff Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Fri, 4 Oct 2024 23:16:33 +0100
Subject: [PATCH 29/29] Enable automatic formatting for ``sphinx/transforms/``
 (#12971)

---
 .ruff.toml                                    |   1 -
 sphinx/transforms/__init__.py                 |  53 ++---
 sphinx/transforms/compact_bullet_list.py      |   5 +-
 sphinx/transforms/i18n.py                     | 182 +++++++++++++-----
 sphinx/transforms/post_transforms/__init__.py | 133 +++++++++----
 sphinx/transforms/post_transforms/code.py     |  13 +-
 sphinx/transforms/post_transforms/images.py   |  20 +-
 7 files changed, 275 insertions(+), 132 deletions(-)

diff --git a/.ruff.toml b/.ruff.toml
index 03ade239ca1..a511d1c242d 100644
--- a/.ruff.toml
+++ b/.ruff.toml
@@ -475,6 +475,5 @@ exclude = [
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
     "sphinx/registry.py",
-    "sphinx/transforms/*",
     "sphinx/writers/*",
 ]
diff --git a/sphinx/transforms/__init__.py b/sphinx/transforms/__init__.py
index a9dedabea28..ca3a533fab0 100644
--- a/sphinx/transforms/__init__.py
+++ b/sphinx/transforms/__init__.py
@@ -120,7 +120,9 @@ def apply(self, **kwargs: Any) -> None:
             if (name := ref['refname']) in to_handle:
                 ref.replace_self(self._handle_default_substitution(name))
 
-    def _handle_default_substitution(self, name: _DEFAULT_SUBSTITUTION_NAMES) -> nodes.Text:
+    def _handle_default_substitution(
+        self, name: _DEFAULT_SUBSTITUTION_NAMES
+    ) -> nodes.Text:
         if name == 'translation progress':
             # special handling: calculate translation progress
             return nodes.Text(_calculate_translation_progress(self.document))
@@ -128,10 +130,8 @@ def _handle_default_substitution(self, name: _DEFAULT_SUBSTITUTION_NAMES) -> nod
             if text := self.config.today:
                 return nodes.Text(text)
             # special handling: can also specify a strftime format
-            return nodes.Text(format_date(
-                self.config.today_fmt or _('%b %d, %Y'),
-                language=self.config.language,
-            ))
+            today_fmt = self.config.today_fmt or _('%b %d, %Y')
+            return nodes.Text(format_date(today_fmt, language=self.config.language))
         # config.version and config.release
         return nodes.Text(getattr(self.config, name))
 
@@ -185,8 +185,7 @@ class HandleCodeBlocks(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         # move doctest blocks out of blockquotes
         for node in self.document.findall(nodes.block_quote):
-            if all(isinstance(child, nodes.doctest_block) for child
-                   in node.children):
+            if all(isinstance(child, nodes.doctest_block) for child in node.children):
                 node.replace_self(node.children)
         # combine successive doctest blocks
         # for node in self.document.findall(nodes.doctest_block):
@@ -211,9 +210,11 @@ def apply(self, **kwargs: Any) -> None:
         domain: StandardDomain = self.env.domains.standard_domain
 
         for node in self.document.findall(nodes.Element):
-            if (domain.is_enumerable_node(node) and
-                    domain.get_numfig_title(node) is not None and
-                    node['ids'] == []):
+            if (
+                domain.is_enumerable_node(node)
+                and domain.get_numfig_title(node) is not None
+                and node['ids'] == []
+            ):
                 self.document.note_implicit_target(node)
 
 
@@ -262,8 +263,13 @@ class AutoIndexUpgrader(SphinxTransform):
     def apply(self, **kwargs: Any) -> None:
         for node in self.document.findall(addnodes.index):
             if 'entries' in node and any(len(entry) == 4 for entry in node['entries']):
-                msg = __('4 column based index found. '
-                         'It might be a bug of extensions you use: %r') % node['entries']
+                msg = (
+                    __(
+                        '4 column based index found. '
+                        'It might be a bug of extensions you use: %r'
+                    )
+                    % node['entries']
+                )
                 logger.warning(msg, location=node)
                 for i, entry in enumerate(node['entries']):
                     if len(entry) == 4:
@@ -302,13 +308,13 @@ def apply(self, **kwargs: Any) -> None:
             # note we do not warn on duplicate footnotes here
             # (i.e. where the name has been moved to dupnames)
             # since this is already reported by docutils
-            if not node['backrefs'] and node["names"]:
+            if not node['backrefs'] and node['names']:
                 logger.warning(
                     __('Footnote [%s] is not referenced.'),
                     node['names'][0] if node['names'] else node['dupnames'][0],
                     type='ref',
                     subtype='footnote',
-                    location=node
+                    location=node,
                 )
         for node in self.document.symbol_footnotes:
             if not node['backrefs']:
@@ -316,18 +322,18 @@ def apply(self, **kwargs: Any) -> None:
                     __('Footnote [*] is not referenced.'),
                     type='ref',
                     subtype='footnote',
-                    location=node
+                    location=node,
                 )
         for node in self.document.autofootnotes:
             # note we do not warn on duplicate footnotes here
             # (i.e. where the name has been moved to dupnames)
             # since this is already reported by docutils
-            if not node['backrefs'] and node["names"]:
+            if not node['backrefs'] and node['names']:
                 logger.warning(
                     __('Footnote [#] is not referenced.'),
                     type='ref',
                     subtype='footnote',
-                    location=node
+                    location=node,
                 )
 
 
@@ -403,10 +409,7 @@ def is_available(self) -> bool:
 
         # confirm selected language supports smart_quotes or not
         language = self.env.settings['language_code']
-        return any(
-            tag in smartchars.quotes
-            for tag in normalize_language_tag(language)
-        )
+        return any(tag in smartchars.quotes for tag in normalize_language_tag(language))
 
     def get_tokens(self, txtnodes: list[Text]) -> Iterator[tuple[str, str]]:
         # A generator that yields ``(texttype, nodetext)`` tuples for a list
@@ -439,13 +442,13 @@ class GlossarySorter(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         for glossary in self.document.findall(addnodes.glossary):
-            if glossary["sorted"]:
+            if glossary['sorted']:
                 definition_list = cast(nodes.definition_list, glossary[0])
                 definition_list[:] = sorted(
                     definition_list,
                     key=lambda item: unicodedata.normalize(
-                        'NFD',
-                        cast(nodes.term, item)[0].astext().lower()),
+                        'NFD', cast(nodes.term, item)[0].astext().lower()
+                    ),
                 )
 
 
@@ -508,7 +511,7 @@ def _reorder_index_target_nodes(start_node: nodes.target) -> None:
         first_idx = parent.index(nodes_to_reorder[0])
         last_idx = parent.index(nodes_to_reorder[-1])
         if first_idx + len(nodes_to_reorder) - 1 == last_idx:
-            parent[first_idx:last_idx + 1] = sorted(nodes_to_reorder, key=_sort_key)
+            parent[first_idx : last_idx + 1] = sorted(nodes_to_reorder, key=_sort_key)
 
 
 def _sort_key(node: nodes.Node) -> int:
diff --git a/sphinx/transforms/compact_bullet_list.py b/sphinx/transforms/compact_bullet_list.py
index acd8634783b..f144df87fb2 100644
--- a/sphinx/transforms/compact_bullet_list.py
+++ b/sphinx/transforms/compact_bullet_list.py
@@ -30,8 +30,9 @@ def visit_bullet_list(self, node: nodes.bullet_list) -> None:
         pass
 
     def visit_list_item(self, node: nodes.list_item) -> None:
-        children: list[Node] = [child for child in node.children
-                                if not isinstance(child, nodes.Invisible)]
+        children: list[Node] = [
+            child for child in node.children if not isinstance(child, nodes.Invisible)
+        ]
         if len(children) != 1:
             raise nodes.NodeFound
         if not isinstance(children[0], nodes.paragraph):
diff --git a/sphinx/transforms/i18n.py b/sphinx/transforms/i18n.py
index 8b67836764a..43449d57a88 100644
--- a/sphinx/transforms/i18n.py
+++ b/sphinx/transforms/i18n.py
@@ -48,8 +48,14 @@
 N = TypeVar('N', bound=nodes.Node)
 
 
-def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
-                   config: Config, settings: Any) -> nodes.Element:
+def publish_msgstr(
+    app: Sphinx,
+    source: str,
+    source_path: str,
+    source_line: int,
+    config: Config,
+    settings: Any,
+) -> nodes.Element:
     """Publish msgstr (single line) into docutils document
 
     :param sphinx.application.Sphinx app: sphinx application
@@ -67,13 +73,15 @@ def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
         config.rst_prolog = None
 
         from sphinx.io import SphinxI18nReader
+
         reader = SphinxI18nReader()
         reader.setup(app)
         filetype = get_filetype(config.source_suffix, source_path)
         parser = app.registry.create_source_parser(app, filetype)
         doc = reader.read(
-            source=StringInput(source=source,
-                               source_path=f"{source_path}:{source_line}:<translated>"),
+            source=StringInput(
+                source=source, source_path=f'{source_path}:{source_line}:<translated>'
+            ),
             parser=parser,
             settings=settings,
         )
@@ -85,7 +93,7 @@ def publish_msgstr(app: Sphinx, source: str, source_path: str, source_line: int,
 
 
 def parse_noqa(source: str) -> tuple[str, bool]:
-    m = match(r"(.*)(?<!\\)#\s*noqa\s*$", source, DOTALL)
+    m = match(r'(.*)(?<!\\)#\s*noqa\s*$', source, DOTALL)
     if m:
         return m.group(1), True
     else:
@@ -108,29 +116,43 @@ class _NodeUpdater:
     """Contains logic for updating one node with the translated content."""
 
     def __init__(
-        self, node: nodes.Element, patch: nodes.Element, document: nodes.document, noqa: bool,
+        self,
+        node: nodes.Element,
+        patch: nodes.Element,
+        document: nodes.document,
+        noqa: bool,
     ) -> None:
         self.node: nodes.Element = node
         self.patch: nodes.Element = patch
         self.document: nodes.document = document
         self.noqa: bool = noqa
 
-    def compare_references(self, old_refs: Sequence[nodes.Element],
-                           new_refs: Sequence[nodes.Element],
-                           warning_msg: str) -> None:
+    def compare_references(
+        self,
+        old_refs: Sequence[nodes.Element],
+        new_refs: Sequence[nodes.Element],
+        warning_msg: str,
+    ) -> None:
         """Warn about mismatches between references in original and translated content."""
         # FIXME: could use a smarter strategy than len(old_refs) == len(new_refs)
         if not self.noqa and len(old_refs) != len(new_refs):
             old_ref_rawsources = [ref.rawsource for ref in old_refs]
             new_ref_rawsources = [ref.rawsource for ref in new_refs]
-            logger.warning(warning_msg.format(old_ref_rawsources, new_ref_rawsources),
-                           location=self.node, type='i18n', subtype='inconsistent_references')
+            logger.warning(
+                warning_msg.format(old_ref_rawsources, new_ref_rawsources),
+                location=self.node,
+                type='i18n',
+                subtype='inconsistent_references',
+            )
 
     def update_title_mapping(self) -> bool:
         processed = False  # skip flag
 
         # update title(section) target name-id mapping
-        if isinstance(self.node, nodes.title) and isinstance(self.node.parent, nodes.section):
+        if (
+            isinstance(self.node, nodes.title)
+            and isinstance(self.node.parent, nodes.section)
+        ):  # fmt: skip
             section_node = self.node.parent
             new_name = nodes.fully_normalize_name(self.patch.astext())
             old_name = nodes.fully_normalize_name(self.node.astext())
@@ -201,9 +223,14 @@ def list_replace_or_append(lst: list[N], old: N, new: N) -> None:
         is_autofootnote_ref = NodeMatcher(nodes.footnote_reference, auto=Any)
         old_foot_refs = list(is_autofootnote_ref.findall(self.node))
         new_foot_refs = list(is_autofootnote_ref.findall(self.patch))
-        self.compare_references(old_foot_refs, new_foot_refs,
-                                __('inconsistent footnote references in translated message.'
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_foot_refs,
+            new_foot_refs,
+            __(
+                'inconsistent footnote references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         old_foot_namerefs: dict[str, list[nodes.footnote_reference]] = {}
         for r in old_foot_refs:
             old_foot_namerefs.setdefault(r.get('refname'), []).append(r)
@@ -241,9 +268,14 @@ def update_refnamed_references(self) -> None:
         is_refnamed_ref = NodeMatcher(nodes.reference, refname=Any)
         old_refs = list(is_refnamed_ref.findall(self.node))
         new_refs = list(is_refnamed_ref.findall(self.patch))
-        self.compare_references(old_refs, new_refs,
-                                __('inconsistent references in translated message.'
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_refs,
+            new_refs,
+            __(
+                'inconsistent references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         old_ref_names = [r['refname'] for r in old_refs]
         new_ref_names = [r['refname'] for r in new_refs]
         orphans = [*({*old_ref_names} - {*new_ref_names})]
@@ -266,31 +298,41 @@ def update_refnamed_footnote_references(self) -> None:
         old_foot_refs = list(is_refnamed_footnote_ref.findall(self.node))
         new_foot_refs = list(is_refnamed_footnote_ref.findall(self.patch))
         refname_ids_map: dict[str, list[str]] = {}
-        self.compare_references(old_foot_refs, new_foot_refs,
-                                __('inconsistent footnote references in translated message.'
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_foot_refs,
+            new_foot_refs,
+            __(
+                'inconsistent footnote references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         for oldf in old_foot_refs:
-            refname_ids_map.setdefault(oldf["refname"], []).append(oldf["ids"])
+            refname_ids_map.setdefault(oldf['refname'], []).append(oldf['ids'])
         for newf in new_foot_refs:
-            refname = newf["refname"]
+            refname = newf['refname']
             if refname_ids_map.get(refname):
-                newf["ids"] = refname_ids_map[refname].pop(0)
+                newf['ids'] = refname_ids_map[refname].pop(0)
 
     def update_citation_references(self) -> None:
         # citation should use original 'ids'.
         is_citation_ref = NodeMatcher(nodes.citation_reference, refname=Any)
         old_cite_refs = list(is_citation_ref.findall(self.node))
         new_cite_refs = list(is_citation_ref.findall(self.patch))
-        self.compare_references(old_cite_refs, new_cite_refs,
-                                __('inconsistent citation references in translated message.'
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_cite_refs,
+            new_cite_refs,
+            __(
+                'inconsistent citation references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
         refname_ids_map: dict[str, list[str]] = {}
         for oldc in old_cite_refs:
-            refname_ids_map.setdefault(oldc["refname"], []).append(oldc["ids"])
+            refname_ids_map.setdefault(oldc['refname'], []).append(oldc['ids'])
         for newc in new_cite_refs:
-            refname = newc["refname"]
+            refname = newc['refname']
             if refname_ids_map.get(refname):
-                newc["ids"] = refname_ids_map[refname].pop()
+                newc['ids'] = refname_ids_map[refname].pop()
 
     def update_pending_xrefs(self) -> None:
         # Original pending_xref['reftarget'] contain not-translated
@@ -298,20 +340,25 @@ def update_pending_xrefs(self) -> None:
         # This code restricts to change ref-targets in the translation.
         old_xrefs = [*self.node.findall(addnodes.pending_xref)]
         new_xrefs = [*self.patch.findall(addnodes.pending_xref)]
-        self.compare_references(old_xrefs, new_xrefs,
-                                __('inconsistent term references in translated message.'
-                                   ' original: {0}, translated: {1}'))
+        self.compare_references(
+            old_xrefs,
+            new_xrefs,
+            __(
+                'inconsistent term references in translated message.'
+                ' original: {0}, translated: {1}'
+            ),
+        )
 
         xref_reftarget_map: dict[tuple[str, str, str] | None, dict[str, Any]] = {}
 
         def get_ref_key(node: addnodes.pending_xref) -> tuple[str, str, str] | None:
-            case = node["refdomain"], node["reftype"]
+            case = node['refdomain'], node['reftype']
             if case == ('std', 'term'):
                 return None
             else:
                 return (
-                    node["refdomain"],
-                    node["reftype"],
+                    node['refdomain'],
+                    node['reftype'],
                     node['reftarget'],
                 )
 
@@ -347,8 +394,10 @@ def apply(self, **kwargs: Any) -> None:
         textdomain = docname_to_domain(self.env.docname, self.config.gettext_compact)
 
         # fetch translations
-        dirs = [path.join(self.env.srcdir, directory)
-                for directory in self.config.locale_dirs]
+        dirs = [
+            path.join(self.env.srcdir, directory)
+            for directory in self.config.locale_dirs
+        ]
         catalog, has_catalog = init_locale(dirs, self.config.language, textdomain)
         if not has_catalog:
             return
@@ -393,8 +442,14 @@ def apply(self, **kwargs: Any) -> None:
             if isinstance(node, LITERAL_TYPE_NODES):
                 msgstr = '::\n\n' + indent(msgstr, ' ' * 3)
 
-            patch = publish_msgstr(self.app, msgstr, source,
-                                   node.line, self.config, settings)  # type: ignore[arg-type]
+            patch = publish_msgstr(
+                self.app,
+                msgstr,
+                source,
+                node.line,  # type: ignore[arg-type]
+                self.config,
+                settings,
+            )
             # FIXME: no warnings about inconsistent references in this part
             # XXX doctest and other block markup
             if not isinstance(patch, nodes.paragraph):
@@ -408,11 +463,21 @@ def apply(self, **kwargs: Any) -> None:
                 for _id in node['ids']:
                     term, first_classifier = split_term_classifiers(msgstr)
                     patch = publish_msgstr(
-                        self.app, term or '', source, node.line, self.config, settings,  # type: ignore[arg-type]
+                        self.app,
+                        term or '',
+                        source,
+                        node.line,  # type: ignore[arg-type]
+                        self.config,
+                        settings,
                     )
                     updater.patch = make_glossary_term(
-                        self.env, patch, first_classifier,
-                        source, node.line, _id, self.document,  # type: ignore[arg-type]
+                        self.env,
+                        patch,
+                        first_classifier,
+                        source,
+                        node.line,  # type: ignore[arg-type]
+                        _id,
+                        self.document,
                     )
                     processed = True
 
@@ -474,8 +539,14 @@ def apply(self, **kwargs: Any) -> None:
                 # This generates: <section ...><title>msgstr</title></section>
                 msgstr = msgstr + '\n' + '=' * len(msgstr) * 2
 
-            patch = publish_msgstr(self.app, msgstr, source,
-                                   node.line, self.config, settings)  # type: ignore[arg-type]
+            patch = publish_msgstr(
+                self.app,
+                msgstr,
+                source,
+                node.line,  # type: ignore[arg-type]
+                self.config,
+                settings,
+            )
             # Structural Subelements phase2
             if isinstance(node, nodes.title):
                 # get <title> node that placed as a first child
@@ -483,8 +554,8 @@ def apply(self, **kwargs: Any) -> None:
 
             # ignore unexpected markups in translation message
             unexpected: tuple[type[nodes.Element], ...] = (
-                nodes.paragraph,    # expected form of translation
-                nodes.title,        # generated by above "Subelements phase2"
+                nodes.paragraph,  # expected form of translation
+                nodes.title,  # generated by above "Subelements phase2"
             )
 
             # following types are expected if
@@ -527,7 +598,13 @@ def apply(self, **kwargs: Any) -> None:
                             msgstr = part
                         msgstr_parts.append(msgstr)
 
-                    new_entry = entry_type, ';'.join(msgstr_parts), target_id, main, None
+                    new_entry = (
+                        entry_type,
+                        ';'.join(msgstr_parts),
+                        target_id,
+                        main,
+                        None,
+                    )
                     new_entries.append(new_entry)
 
                 node['raw_entries'] = entries
@@ -543,6 +620,7 @@ class TranslationProgressTotaliser(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return
 
@@ -567,6 +645,7 @@ class AddTranslationClasses(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return
 
@@ -582,8 +661,10 @@ def apply(self, **kwargs: Any) -> None:
             add_translated = False
             add_untranslated = True
         else:
-            msg = ('translation_progress_classes must be '
-                   'True, False, "translated" or "untranslated"')
+            msg = (
+                'translation_progress_classes must be '
+                'True, False, "translated" or "untranslated"'
+            )
             raise ConfigError(msg)
 
         for node in NodeMatcher(nodes.Element, translated=Any).findall(self.document):
@@ -604,6 +685,7 @@ class RemoveTranslatableInline(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         from sphinx.builders.gettext import MessageCatalogBuilder
+
         if isinstance(self.app.builder, MessageCatalogBuilder):
             return
 
diff --git a/sphinx/transforms/post_transforms/__init__.py b/sphinx/transforms/post_transforms/__init__.py
index 82de90a6e3f..07e28500c9e 100644
--- a/sphinx/transforms/post_transforms/__init__.py
+++ b/sphinx/transforms/post_transforms/__init__.py
@@ -66,7 +66,7 @@ class ReferencesResolver(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         for node in self.document.findall(addnodes.pending_xref):
-            content = self.find_pending_xref_condition(node, ("resolved", "*"))
+            content = self.find_pending_xref_condition(node, ('resolved', '*'))
             if content:
                 contnode = cast(Element, content[0].deepcopy())
             else:
@@ -87,16 +87,21 @@ def run(self, **kwargs: Any) -> None:
                         domain = self.env.domains[node['refdomain']]
                     except KeyError as exc:
                         raise NoUri(target, typ) from exc
-                    newnode = domain.resolve_xref(self.env, refdoc, self.app.builder,
-                                                  typ, target, node, contnode)
+                    newnode = domain.resolve_xref(
+                        self.env, refdoc, self.app.builder, typ, target, node, contnode
+                    )
                 # really hardwired reference types
                 elif typ == 'any':
                     newnode = self.resolve_anyref(refdoc, node, contnode)
                 # no new node found? try the missing-reference event
                 if newnode is None:
-                    newnode = self.app.emit_firstresult('missing-reference', self.env,
-                                                        node, contnode,
-                                                        allowed_exceptions=(NoUri,))
+                    newnode = self.app.emit_firstresult(
+                        'missing-reference',
+                        self.env,
+                        node,
+                        contnode,
+                        allowed_exceptions=(NoUri,),
+                    )
                     # still not found? warn if node wishes to be warned about or
                     # we are in nitpicky mode
                     if newnode is None:
@@ -108,69 +113,103 @@ def run(self, **kwargs: Any) -> None:
                 newnodes: list[Node] = [newnode]
             else:
                 newnodes = [contnode]
-                if newnode is None and isinstance(node[0], addnodes.pending_xref_condition):
-                    matched = self.find_pending_xref_condition(node, ("*",))
+                if newnode is None and isinstance(
+                    node[0], addnodes.pending_xref_condition
+                ):
+                    matched = self.find_pending_xref_condition(node, ('*',))
                     if matched:
                         newnodes = matched
                     else:
-                        logger.warning(__('Could not determine the fallback text for the '
-                                          'cross-reference. Might be a bug.'), location=node)
+                        logger.warning(
+                            __(
+                                'Could not determine the fallback text for the '
+                                'cross-reference. Might be a bug.'
+                            ),
+                            location=node,
+                        )
 
             node.replace_self(newnodes)
 
     def resolve_anyref(
-        self, refdoc: str, node: pending_xref, contnode: Element,
+        self,
+        refdoc: str,
+        node: pending_xref,
+        contnode: Element,
     ) -> Element | None:
         """Resolve reference generated by the "any" role."""
         stddomain = self.env.domains.standard_domain
         target = node['reftarget']
         results: list[tuple[str, Element]] = []
         # first, try resolving as :doc:
-        doc_ref = stddomain.resolve_xref(self.env, refdoc, self.app.builder,
-                                         'doc', target, node, contnode)
+        doc_ref = stddomain.resolve_xref(
+            self.env, refdoc, self.app.builder, 'doc', target, node, contnode
+        )
         if doc_ref:
             results.append(('doc', doc_ref))
         # next, do the standard domain (makes this a priority)
-        results.extend(stddomain.resolve_any_xref(self.env, refdoc, self.app.builder,
-                                                  target, node, contnode))
+        results.extend(
+            stddomain.resolve_any_xref(
+                self.env, refdoc, self.app.builder, target, node, contnode
+            )
+        )
         for domain in self.env.domains.sorted():
             if domain.name == 'std':
                 continue  # we did this one already
             try:
-                results.extend(domain.resolve_any_xref(self.env, refdoc, self.app.builder,
-                                                       target, node, contnode))
+                results.extend(
+                    domain.resolve_any_xref(
+                        self.env, refdoc, self.app.builder, target, node, contnode
+                    )
+                )
             except NotImplementedError:
                 # the domain doesn't yet support the new interface
                 # we have to manually collect possible references (SLOW)
                 for role in domain.roles:
-                    res = domain.resolve_xref(self.env, refdoc, self.app.builder,
-                                              role, target, node, contnode)
+                    res = domain.resolve_xref(
+                        self.env, refdoc, self.app.builder, role, target, node, contnode
+                    )
                     if res and len(res) > 0 and isinstance(res[0], nodes.Element):
                         results.append((f'{domain.name}:{role}', res))
         # now, see how many matches we got...
         if not results:
             return None
         if len(results) > 1:
+
             def stringify(name: str, node: Element) -> str:
                 reftitle = node.get('reftitle', node.astext())
                 return f':{name}:`{reftitle}`'
+
             candidates = ' or '.join(starmap(stringify, results))
-            logger.warning(__("more than one target found for 'any' cross-"
-                              'reference %r: could be %s'), target, candidates,
-                           location=node)
+            logger.warning(
+                __(
+                    "more than one target found for 'any' cross-"
+                    'reference %r: could be %s'
+                ),
+                target,
+                candidates,
+                location=node,
+            )
         res_role, newnode = results[0]
         # Override "any" class with the actual role type to get the styling
         # approximately correct.
         res_domain = res_role.split(':')[0]
-        if (len(newnode) > 0 and
-                isinstance(newnode[0], nodes.Element) and
-                newnode[0].get('classes')):
+        if (
+            len(newnode) > 0
+            and isinstance(newnode[0], nodes.Element)
+            and newnode[0].get('classes')
+        ):
             newnode[0]['classes'].append(res_domain)
             newnode[0]['classes'].append(res_role.replace(':', '-'))
         return newnode
 
-    def warn_missing_reference(self, refdoc: str, typ: str, target: str,
-                               node: pending_xref, domain: Domain | None) -> None:
+    def warn_missing_reference(
+        self,
+        refdoc: str,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        domain: Domain | None,
+    ) -> None:
         warn = node.get('refwarn')
         if self.config.nitpicky:
             warn = True
@@ -179,24 +218,26 @@ def warn_missing_reference(self, refdoc: str, typ: str, target: str,
                 if (dtype, target) in self.config.nitpick_ignore:
                     warn = False
                 # for "std" types also try without domain name
-                if (not domain or domain.name == 'std') and \
-                   (typ, target) in self.config.nitpick_ignore:
+                if (
+                    (not domain or domain.name == 'std')
+                    and (typ, target) in self.config.nitpick_ignore
+                ):  # fmt: skip
                     warn = False
             if self.config.nitpick_ignore_regex:
+
                 def matches_ignore(entry_type: str, entry_target: str) -> bool:
                     return any(
                         (
                             re.fullmatch(ignore_type, entry_type)
                             and re.fullmatch(ignore_target, entry_target)
                         )
-                        for ignore_type, ignore_target
-                        in self.config.nitpick_ignore_regex
+                        for ignore_type, ignore_target in self.config.nitpick_ignore_regex
                     )
+
                 if matches_ignore(dtype, target):
                     warn = False
                 # for "std" types also try without domain name
-                if (not domain or domain.name == 'std') and \
-                   matches_ignore(typ, target):
+                if (not domain or domain.name == 'std') and matches_ignore(typ, target):
                     warn = False
         if not warn:
             return
@@ -206,14 +247,20 @@ def matches_ignore(entry_type: str, entry_target: str) -> bool:
         elif domain and typ in domain.dangling_warnings:
             msg = domain.dangling_warnings[typ] % {'target': target}
         elif node.get('refdomain', 'std') not in ('', 'std'):
-            msg = (__('%s:%s reference target not found: %s') %
-                   (node['refdomain'], typ, target))
+            msg = __('%s:%s reference target not found: %s') % (
+                node['refdomain'],
+                typ,
+                target,
+            )
         else:
             msg = __('%r reference target not found: %s') % (typ, target)
         logger.warning(msg, location=node, type='ref', subtype=typ)
 
-    def find_pending_xref_condition(self, node: pending_xref, conditions: Sequence[str],
-                                    ) -> list[Node] | None:
+    def find_pending_xref_condition(
+        self,
+        node: pending_xref,
+        conditions: Sequence[str],
+    ) -> list[Node] | None:
         for condition in conditions:
             matched = find_pending_xref_condition(node, condition)
             if matched:
@@ -238,8 +285,10 @@ class SigElementFallbackTransform(SphinxPostTransform):
     default_priority = 200
 
     def run(self, **kwargs: Any) -> None:
-        def has_visitor(translator: type[nodes.NodeVisitor], node: type[Element]) -> bool:
-            return hasattr(translator, "visit_%s" % node.__name__)
+        def has_visitor(
+            translator: type[nodes.NodeVisitor], node: type[Element]
+        ) -> bool:
+            return hasattr(translator, 'visit_%s' % node.__name__)
 
         try:
             translator = self.app.builder.get_translator_class()
@@ -253,8 +302,10 @@ def has_visitor(translator: type[nodes.NodeVisitor], node: type[Element]) -> boo
 
         # for the leaf elements (desc_sig_element), the translator should support _all_,
         # unless there exists a generic visit_desc_sig_element default visitor
-        if (not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
-                and not has_visitor(translator, addnodes.desc_sig_element)):
+        if (
+            not all(has_visitor(translator, node) for node in addnodes.SIG_ELEMENTS)
+            and not has_visitor(translator, addnodes.desc_sig_element)
+        ):  # fmt: skip
             self.fallback(addnodes.desc_sig_element)
 
         if not has_visitor(translator, addnodes.desc_inline):
diff --git a/sphinx/transforms/post_transforms/code.py b/sphinx/transforms/post_transforms/code.py
index 4375b4d89c2..4abf5aed10f 100644
--- a/sphinx/transforms/post_transforms/code.py
+++ b/sphinx/transforms/post_transforms/code.py
@@ -37,8 +37,9 @@ class HighlightLanguageTransform(SphinxTransform):
     default_priority = 400
 
     def apply(self, **kwargs: Any) -> None:
-        visitor = HighlightLanguageVisitor(self.document,
-                                           self.config.highlight_language)
+        visitor = HighlightLanguageVisitor(
+            self.document, self.config.highlight_language
+        )
         self.document.walkabout(visitor)
 
         for node in list(self.document.findall(addnodes.highlightlang)):
@@ -70,9 +71,9 @@ def depart_start_of_file(self, node: Node) -> None:
         self.settings.pop()
 
     def visit_highlightlang(self, node: addnodes.highlightlang) -> None:
-        self.settings[-1] = HighlightSetting(node['lang'],
-                                             node['force'],
-                                             node['linenothreshold'])
+        self.settings[-1] = HighlightSetting(
+            node['lang'], node['force'], node['linenothreshold']
+        )
 
     def visit_literal_block(self, node: nodes.literal_block) -> None:
         setting = self.settings[-1]
@@ -81,7 +82,7 @@ def visit_literal_block(self, node: nodes.literal_block) -> None:
             node['force'] = setting.force
         if 'linenos' not in node:
             lines = node.astext().count('\n')
-            node['linenos'] = (lines >= setting.lineno_threshold - 1)
+            node['linenos'] = lines >= setting.lineno_threshold - 1
 
 
 class TrimDoctestFlagsTransform(SphinxTransform):
diff --git a/sphinx/transforms/post_transforms/images.py b/sphinx/transforms/post_transforms/images.py
index 05b07dd2232..fd8556aa55c 100644
--- a/sphinx/transforms/post_transforms/images.py
+++ b/sphinx/transforms/post_transforms/images.py
@@ -63,8 +63,10 @@ def handle(self, node: nodes.image) -> None:
                 basename = basename.split('?')[0]
             if basename == '' or len(basename) > MAX_FILENAME_LEN:
                 filename, ext = os.path.splitext(node['uri'])
-                basename = sha1(filename.encode(), usedforsecurity=False).hexdigest() + ext
-            basename = CRITICAL_PATH_CHAR_RE.sub("_", basename)
+                basename = (
+                    sha1(filename.encode(), usedforsecurity=False).hexdigest() + ext
+                )
+            basename = CRITICAL_PATH_CHAR_RE.sub('_', basename)
 
             uri_hash = sha1(node['uri'].encode(), usedforsecurity=False).hexdigest()
             path = Path(self.imagedir, uri_hash, basename)
@@ -83,7 +85,8 @@ def _download_image(self, node: nodes.image, path: Path) -> None:
 
         config = self.app.config
         r = requests.get(
-            node['uri'], headers=headers,
+            node['uri'],
+            headers=headers,
             _user_agent=config.user_agent,
             _tls_info=(config.tls_verify, config.tls_cacerts),
         )
@@ -134,8 +137,9 @@ def handle(self, node: nodes.image) -> None:
         assert image is not None
         ext = get_image_extension(image.mimetype)
         if ext is None:
-            logger.warning(__('Unknown image format: %s...'), node['uri'][:32],
-                           location=node)
+            logger.warning(
+                __('Unknown image format: %s...'), node['uri'][:32], location=node
+            )
             return
 
         ensuredir(os.path.join(self.imagedir, 'embeded'))
@@ -155,7 +159,7 @@ def handle(self, node: nodes.image) -> None:
 
 def get_filename_for(filename: str, mimetype: str) -> str:
     basename = os.path.basename(filename)
-    basename = CRITICAL_PATH_CHAR_RE.sub("_", basename)
+    basename = CRITICAL_PATH_CHAR_RE.sub('_', basename)
     return os.path.splitext(basename)[0] + (get_image_extension(mimetype) or '')
 
 
@@ -206,7 +210,9 @@ def match(self, node: nodes.image) -> bool:
             return False
         if '?' in node['candidates']:
             return False
-        if set(self.guess_mimetypes(node)) & set(self.app.builder.supported_image_types):
+        node_mime_types = set(self.guess_mimetypes(node))
+        supported_image_types = set(self.app.builder.supported_image_types)
+        if node_mime_types & supported_image_types:
             # builder supports the image; no need to convert
             return False
         if self.available is None: