Merge branch 'master' into toctree-glob-warn

.github/workflows/main.yml

@@ -23,6 +23,7 @@ env:
   FORCE_COLOR: "1"
   PYTHONDEVMODE: "1"  # -X dev
   PYTHONWARNDEFAULTENCODING: "1"  # -X warn_default_encoding
+  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
 
 jobs:
   ubuntu:
@@ -124,6 +125,38 @@ jobs:
         DO_EPUBCHECK: "1"
         EPUBCHECK_PATH: "/tmp/epubcheck/epubcheck-5.1.0/epubcheck.jar"
 
+  oldest-supported:
+    runs-on: ubuntu-latest
+    name: Oldest supported
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Check Python version
+      run: python --version --version
+    - name: Install graphviz
+      run: sudo apt-get install graphviz
+    - name: Install uv
+      run: > 
+        curl 
+        --location 
+        --fail
+        --proto '=https' --tlsv1.2 
+        --silent --show-error 
+        https://astral.sh/uv/install.sh
+        | sh
+    - name: Install dependencies
+      run: |
+        uv pip install .[test] --resolution lowest-direct
+        uv pip install alabaster==1.0.0
+    - name: Test with pytest
+      run: python -m pytest -vv --durations 25
+      env:
+        PYTHONWARNINGS: "error"  # treat all warnings as errors
+
   latex:
     runs-on: ubuntu-latest
     name: LaTeX

.github/workflows/nodejs.yml

@@ -6,15 +6,13 @@ on:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
       - "tests/js/**"
-      - "karma.conf.js"
       - "package.json"
       - "package-lock.json"
   pull_request:
     paths:
       - ".github/workflows/nodejs.yml"
       - "sphinx/themes/**.js"
       - "tests/js/**"
-      - "karma.conf.js"
       - "package.json"
       - "package-lock.json"
 

.ruff.toml

@@ -1,5 +1,5 @@
 target-version = "py310"  # Pin Ruff to Python 3.10
-line-length = 95
+line-length = 88
 output-format = "full"
 
 extend-exclude = [
@@ -427,6 +427,9 @@ select = [
     "ANN",  # utilities don't need annotations
 ]
 
+[lint.pycodestyle]
+max-line-length = 95
+
 [lint.flake8-quotes]
 inline-quotes = "single"
 
@@ -482,18 +485,4 @@ exclude = [
     "sphinx/transforms/*",
     "sphinx/util/*",
     "sphinx/writers/*",
-    "tests/*",
-    "tests/roots/*",
-    "tests/test_builders/*",
-    "tests/test_config/*",
-    "tests/test_directives/*",
-    "tests/test_domains/*",
-    "tests/test_environment/*",
-    "tests/test_extensions/*",
-    "tests/test_intl/*",
-    "tests/test_markup/*",
-    "tests/test_pycode/*",
-    "tests/test_transforms/*",
-    "tests/test_util/*",
-    "tests/test_writers/*",
 ]

CHANGES.rst

@@ -4,21 +4,49 @@ Release 8.1.0 (in development)
 Dependencies
 ------------
 
+* #12756: Add lower-bounds to the ``sphinxcontrib-*`` dependencies.
+  Patch by Adam Turner.
+
 Incompatible changes
 --------------------
 
+* #12763: Remove unused internal class ``sphinx.util.Tee``.
+  Patch by Adam Turner.
+
 Deprecated
 ----------
 
+* #12762: Deprecate ``sphinx.util.import_object``.
+  Use :py:func:`importlib.import_module` instead.
+  Patch by Adam Turner.
+* #12766: Deprecate ``sphinx.util.FilenameUniqDict``
+  and ``sphinx.util.DownloadFiles``.
+  Patch by Adam Turner.
+
 Features added
 --------------
 
+* #11328: Mention evaluation of templated content during production of static
+  output files.
+
 Bugs fixed
 ----------
 
 * #12514: intersphinx: fix the meaning of a negative value for
   :confval:`intersphinx_cache_limit`.
   Patch by Shengyu Zhang.
+* #12730: The ``UnreferencedFootnotesDetector`` transform has been improved
+  to more consistently detect unreferenced footnotes.
+  Note, the priority of the transform has been changed from 200 to 622,
+  so that it now runs after the docutils ``Footnotes`` resolution transform.
+  Patch by Chris Sewell.
+* #12587: Do not warn when potential ambiguity detected during Intersphinx
+  resolution occurs due to duplicate targets that differ case-insensitively.
+  Patch by James Addison.
 
 Testing
 -------
+
+* #12141: Migrate from the deprecated ``karma`` JavaScript test framework to
+  the actively-maintained ``jasmine`` framework.  Test coverage is unaffected.
+  Patch by James Addison.

doc/conf.py

@@ -77,7 +77,14 @@
 epub_description = 'Sphinx documentation generator system manual'
 
 latex_documents = [
-    ('index', 'sphinx.tex', 'Sphinx Documentation', 'the Sphinx developers', 'manual', 1)
+    (
+        'index',
+        'sphinx.tex',
+        'Sphinx Documentation',
+        'the Sphinx developers',
+        'manual',
+        1,
+    )
 ]
 latex_logo = '_static/sphinx.png'
 latex_elements = {
@@ -324,7 +331,9 @@ def setup(app: Sphinx) -> None:
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
     app.connect('include-read', linkify_issues_in_changelog)
     app.connect('build-finished', build_redirects)
-    fdesc = GroupedField('parameter', label='Parameters', names=['param'], can_collapse=True)
+    fdesc = GroupedField(
+        'parameter', label='Parameters', names=['param'], can_collapse=True
+    )
     app.add_object_type(
         'event',
         'event',

doc/development/tutorials/examples/recipe.py

@@ -62,7 +62,15 @@ def generate(self, docnames=None):
         for ingredient, recipe_names in ingredient_recipes.items():
             for recipe_name in recipe_names:
                 dispname, typ, docname, anchor = recipes[recipe_name]
-                content[ingredient].append((dispname, 0, docname, anchor, docname, '', typ))
+                content[ingredient].append((
+                    dispname,
+                    0,
+                    docname,
+                    anchor,
+                    docname,
+                    '',
+                    typ,
+                ))
 
         # convert the dict to the sorted list of tuples expected
         content = sorted(content.items())
@@ -153,7 +161,14 @@ def add_recipe(self, signature, ingredients):
 
         self.data['recipe_ingredients'][name] = ingredients
         # name, dispname, type, docname, anchor, priority
-        self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0))
+        self.data['recipes'].append((
+            name,
+            signature,
+            'Recipe',
+            self.env.docname,
+            anchor,
+            0,
+        ))
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

doc/development/tutorials/examples/todo.py

@@ -57,7 +57,9 @@ def purge_todos(app, env, docname):
     if not hasattr(env, 'todo_all_todos'):
         return
 
-    env.todo_all_todos = [todo for todo in env.todo_all_todos if todo['docname'] != docname]
+    env.todo_all_todos = [
+        todo for todo in env.todo_all_todos if todo['docname'] != docname
+    ]
 
 
 def merge_todos(app, env, docnames, other):
@@ -98,7 +100,9 @@ def process_todo_nodes(app, doctree, fromdocname):
             newnode = nodes.reference('', '')
             innernode = nodes.emphasis(_('here'), _('here'))
             newnode['refdocname'] = todo_info['docname']
-            newnode['refuri'] = app.builder.get_relative_uri(fromdocname, todo_info['docname'])
+            newnode['refuri'] = app.builder.get_relative_uri(
+                fromdocname, todo_info['docname']
+            )
             newnode['refuri'] += '#' + todo_info['target']['refid']
             newnode.append(innernode)
             para += newnode

doc/extdev/deprecated.rst

@@ -22,6 +22,21 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.util.FilenameUniqDict``
+     - 8.1
+     - 10.0
+     - N/A
+
+   * - ``sphinx.util.DownloadFiles``
+     - 8.1
+     - 10.0
+     - N/A
+
+   * - ``sphinx.util.import_object``
+     - 8.1
+     - 10.0
+     - ``importlib.import_module``
+
    * - ``sphinx.ext.intersphinx.normalize_intersphinx_mapping``
      - 8.0
      - 10.0

doc/extdev/testing.rst

@@ -28,5 +28,5 @@ Usage
 -----
 
 If you want to know more detailed usage,
-please refer to :file:`tests/conftest.py`` and other :file:`test_*.py` files
+please refer to :file:`tests/conftest.py` and other :file:`test_*.py` files
 under the :file:`tests/` directory.

doc/internals/contributing.rst

@@ -174,10 +174,10 @@ Style and type checks can be run as follows:
 Unit tests
 ~~~~~~~~~~
 
-Sphinx is tested using pytest_ for Python code and Karma_ for JavaScript.
+Sphinx is tested using pytest_ for Python code and Jasmine_ for JavaScript.
 
 .. _pytest: https://docs.pytest.org/en/latest/
-.. _Karma: https://karma-runner.github.io
+.. _Jasmine: https://jasmine.github.io/
 
 To run Python unit tests, we recommend using :program:`tox`, which provides a number
 of targets and allows testing against multiple different Python environments:
@@ -216,13 +216,10 @@ To run JavaScript tests, use :program:`npm`:
 
 .. tip::
 
-   :program:`karma` requires a Firefox binary to use as a test browser.
+   :program:`jasmine` requires a Firefox binary to use as a test browser.
 
-   For Unix-based systems, you can specify the path to the Firefox binary using:
-
-   .. code-block:: shell
-
-      FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test
+   On Unix systems, you can check the presence and location of the ``firefox``
+   binary at the command-line by running ``command -v firefox``.
 
 New unit tests should be included in the :file:`tests/` directory where necessary: