Merge branch 'master' into latex_xelatex_math

Author: jfbu

.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,6 +4,9 @@ Release 8.1.0 (in development)
 Dependencies
 ------------
 
+* #12756: Add lower-bounds to the ``sphinxcontrib-*`` dependencies.
+  Patch by Adam Turner.
+
 Incompatible changes
 --------------------
 
@@ -20,29 +23,52 @@ Incompatible changes
   - For ``'pdflatex'`` as :confval:`latex_engine`, it is planned to replace at
     Sphinx 9 usage of ``amssymb`` by ``stix2`` in order for the math glyphs to
     much better match the default Times-like text font.
+* #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.
 * #12714: LaTeX: Let ``\mathbf{\Lambda}`` work as expected if
   :confval:`latex_engine` is ``'xelatex'`` or ``'lualatex'``, via usage
   of ``unicode-math`` with XITS Math font.
 
 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