Merge branch 'master' into latexpdf_q_Q

.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,27 +4,51 @@ 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.
+* #12474: Support type-dependent search result highlighting via CSS.
+  Patch by Tim Hoffmann.
+
 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.
+* #12639: Fix singular and plural search results text.
+  Patch by Hugo van Kemenade.
+* #12645: Correctly support custom gettext output templates.
+  Patch by Jeremy Bowman.
 * #12717: LaTeX: let :option:`-q <sphinx-build -q>` (quiet) option for
   :program:`sphinx-build -M latexpdf` or :program:`make latexpdf` (``O=-q``)
   get passed to :program:`latexmk`.  Let :option:`-Q <sphinx-build -Q>`
@@ -33,3 +57,7 @@ Bugs fixed
 
 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/_themes/sphinx13/static/sphinx13.css

@@ -691,7 +691,28 @@ div.sphinx-feature > p.admonition-title::before {
     justify-content: center;
     gap: 10px;
 }
-
 .sphinx-users-logos .headerlink {
     display: none;
 }
+
+/* -- search results -------------------------------------------------------- */
+
+ul.search {
+    padding-left: 30px;
+}
+ul.search li {
+    padding: 5px 0 5px 10px;
+    list-style-type: "\25A1";  /* Unicode: White Square */
+}
+ul.search li.context-index {
+    list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
+}
+ul.search li.context-object {
+    list-style-type: "\1F4E6";  /* Unicode: Package */
+}
+ul.search li.context-title {
+    list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
+}
+ul.search li.context-text {
+    list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
+}

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/html_themes/index.rst

@@ -221,6 +221,64 @@ If your theme package contains two or more themes, please call
    ``sphinx.html_themes`` entry_points feature.
 
 
+Styling with CSS
+----------------
+
+The :confval:`!stylesheets` setting can be used to add custom CSS files to a theme.
+
+.. caution::
+
+   The structure of the HTML elements and their classes are currently not a
+   well-defined public API. Please infer them from inspecting the built HTML
+   pages. While we cannot guarantee full stability, they tend to be fairly
+   stable.
+
+Styling search result entries by category
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 8.0
+
+The search result items have classes indicating the context in which the
+search term was found. You can use the CSS selectors:
+
+- ``ul.search li.context-index``:
+  For results in an index, such as the glossary
+- ``ul.search li.context-object``:
+  For results in source code, like Python function definitions
+- ``ul.search li.context-title``:
+  For results found in section headings
+- ``ul.search li.context-text``:
+  For results found anywhere else in the documentation text
+
+As a base for inheritance by other themes, the ``basic`` theme is
+intentionally minimal and does not define CSS rules using these.
+Derived themes are encouraged to use these selectors as they see fit.
+For example, the following stylesheet adds contextual icons to the
+search result list:
+
+.. code-block:: css
+
+    ul.search {
+        padding-left: 30px;
+    }
+    ul.search li {
+        padding: 5px 0 5px 10px;
+        list-style-type: "\25A1";  /* Unicode: White Square */
+    }
+    ul.search li.context-index {
+        list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
+    }
+    ul.search li.context-object {
+        list-style-type: "\1F4E6";  /* Unicode: Package */
+    }
+    ul.search li.context-title {
+        list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
+    }
+    ul.search li.context-text {
+        list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
+    }
+
+
 Templating
 ----------
 

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: