Merge branch 'master' into toctree-fix

.github/workflows/lint.yml

@@ -16,6 +16,8 @@ env:
   FORCE_COLOR: "1"
 
 jobs:
+  # If you update any of these commands, don't forget to update the equivalent
+  # tox environment
   ruff:
     runs-on: ubuntu-latest
 

.github/workflows/nodejs.yml

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

.gitignore

@@ -31,6 +31,7 @@ doc/_build/
 doc/locale/
 tests/.coverage
 tests/build/
+tests/js/roots/*/_build
 tests/test-server.lock
 utils/regression_test.js
 

.ruff.toml

@@ -4,6 +4,7 @@ output-format = "full"
 
 extend-exclude = [
     "tests/roots/*",
+    "tests/js/roots/*",
     "build/*",
     "doc/_build/*",
     "sphinx/search/*",
@@ -221,7 +222,6 @@ select = [
 #    "PLR0912",  # Too many branches ({branches} > {max_branches})
 #    "PLR0913",  # Too many arguments to function call ({c_args} > {max_args})
 #    "PLR0915",  # Too many statements ({statements} > {max_statements})
-    "PLR1701",  # Merge `isinstance` calls: `{expr}`
     "PLR1711",  # Useless `return` statement at end of function
 #    "PLR1714",  # Consider merging multiple comparisons: `{expr}`. Use a `set` if the elements are hashable.
     "PLR1722",  # Use `sys.exit()` instead of `{name}`
@@ -372,6 +372,7 @@ select = [
 [lint.per-file-ignores]
 "doc/*" = [
     "ANN",  # documentation doesn't need annotations
+    "TCH001",  # documentation doesn't need type-checking blocks
 ]
 "doc/conf.py" = ["INP001", "W605"]
 "doc/development/tutorials/examples/*" = ["INP001"]
@@ -447,7 +448,32 @@ exclude = [
     "sphinx/directives/*",
     "sphinx/domains/*",
     "sphinx/environment/*",
-    "sphinx/ext/*",
+    "sphinx/ext/autodoc/__init__.py",
+    "sphinx/ext/autodoc/directive.py",
+    "sphinx/ext/autodoc/importer.py",
+    "sphinx/ext/autodoc/mock.py",
+    "sphinx/ext/autodoc/preserve_defaults.py",
+    "sphinx/ext/autodoc/type_comment.py",
+    "sphinx/ext/autodoc/typehints.py",
+    "sphinx/ext/autosectionlabel.py",
+    "sphinx/ext/autosummary/__init__.py",
+    "sphinx/ext/coverage.py",
+    "sphinx/ext/doctest.py",
+    "sphinx/ext/duration.py",
+    "sphinx/ext/extlinks.py",
+    "sphinx/ext/githubpages.py",
+    "sphinx/ext/graphviz.py",
+    "sphinx/ext/ifconfig.py",
+    "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",
+    "sphinx/ext/napoleon/docstring.py",
+    "sphinx/ext/todo.py",
+    "sphinx/ext/viewcode.py",
     "sphinx/pycode/*",
     "sphinx/pygments_styles.py",
     "sphinx/registry.py",

CHANGES.rst

@@ -21,6 +21,62 @@ Features added
 * Flatten ``Union[Literal[T], Literal[U], ...]`` to ``Literal[T, U, ...]``
   when turning annotations into strings.
   Patch by Adam Turner.
+* #12319: ``sphinx.ext.extlinks``: Add ``extlink-{name}`` CSS class to links.
+  Patch by Hugo van Kemenade.
+* #12387: Improve CLI progress message, when copying assets.
+  Patch by INADA Nakoi and Bénédikt Tran.
+* #12361: Add :attr:`.BuildEnvironment.parser`.
+  Patch by Chris Sewell.
+* #12358: Add :attr:`.Sphinx.fresh_env_used`.
+  Patch by Chris Sewell.
+* #12329: Add detection of ambiguous ``std:label`` and ``std:term`` references during
+  loading and resolution of Intersphinx targets.
+  Patch by James Addison.
+* #12422: Do not duplicate "navigation" in aria-label of built-in themes.
+  Patch by Thomas Weißschuh
+* #12421: Include project name in ``logo_alt`` of built-in themes.
+  Patch by Thomas Weißschuh
+* #12448: Add :option:`sphinx-apidoc --remove-old` option.
+  Patch by Chris Sewell.
+* #12456: Add :option:`sphinx-autogen --remove-old` option.
+  Patch by Chris Sewell.
+* #12479: Add warning subtype ``toc.no_title``.
+  Patch by Ondřej Navrátil.
+* #12492: Add helper methods for parsing reStructuredText content into nodes from
+  within a directive.
+
+  - :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_content_to_nodes()`
+    parses the directive's content and returns a list of Docutils nodes.
+  - :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_text_to_nodes()`
+    parses the provided text and returns a list of Docutils nodes.
+  - :py:meth:`~sphinx.util.docutils.SphinxDirective.parse_inline()`
+    parses the provided text into inline elements and text nodes.
+
+  Patch by Adam Turner.
+
+* #12258: Support ``typing_extensions.Unpack``
+  Patch by Bénédikt Tran and Adam Turner.
+* #12524: Add a ``class`` option to the :rst:dir:`toctree` directive.
+  Patch by Tim Hoffmann.
+* #12536: Add the :rst:dir:`confval` directive.
+  Patch by Adam Turner.
+* #12537: :confval:`c_id_attributes`, :confval:`c_paren_attributes`,
+  :confval:`cpp_id_attributes`, and :confval:`cpp_paren_attributes`
+  can now be a tuple of strings.
+  :confval:`c_extra_keywords`, :confval:`gettext_additional_targets`,
+  :confval:`html_domain_indices`, :confval:`latex_domain_indices`,
+  and :confval:`texinfo_domain_indices`,
+  can now be a set of strings.
+  Patch by Adam Turner.
+* #12523: Added configuration option, :confval:`math_numsep`, to define the
+  separator for math numbering.
+  Patch by Thomas Fanning
+* #11592: Add :confval:`coverage_modules` to the coverage builder
+  to allow explicitly specifying which modules should be documented.
+  Patch by Stephen Finucane.
+* #7896, #11989: Add a :rst:dir:`py:type` directiv for documenting type aliases,
+  and a :rst:role:`py:type` role for linking to them.
+  Patch by Ashley Whetter.
 
 Bugs fixed
 ----------
@@ -36,10 +92,40 @@ Bugs fixed
   Patch by Matthias Geier.
 * #12224: Properly detect WebP files.
   Patch by Benjamin Cabé.
+* #12380: LaTeX: Footnote mark sometimes indicates ``Page N`` where ``N`` is
+  the current page number and the footnote does appear on that same page.
+  Patch by Jean-François B.
+* #12416: Ensure that configuration setting aliases are always synchronised
+  when one value or the other is modified.
+  Patch by Bénédikt Tran.
+* #12220: Fix loading custom template translations for ``en`` locale.
+  Patch by Nicolas Peugnet.
+* #12459: Add valid-type arguments to the ``linkcheck_rate_limit_timeout``
+  configuration setting.
+  Patch by James Addison.
+* #12331: Resolve data-URI-image-extraction regression from v7.3.0 affecting
+  builders without native support for data-URIs in their output format.
+  Patch by James Addison.
+* #12494: Fix invalid genindex.html file produced with translated docs
+  (regression in 7.1.0).
+  Patch by Nicolas Peugnet.
+* #11961: Omit anchor references from document title entries in the search index,
+  removing duplication of search results.
+  Patch by James Addison.
+* #12425: Use Docutils' SVG processing in the HTML builder
+  and remove Sphinx's custom logic.
+  Patch by Tunç Başar Köse.
+* #12391: Adjust scoring of matches during HTML search so that document main
+  titles tend to rank higher than subsection titles. In addition, boost matches
+  on the name of programming domain objects relative to title/subtitle matches.
+  Patch by James Addison and Will Lachance.
 
 Testing
 -------
 
+* karma: refactor HTML search tests to use fixtures generated by Sphinx.
+  Patch by James Addison.
+
 Release 7.3.7 (released Apr 19, 2024)
 =====================================
 
@@ -1977,13 +2063,13 @@ Features added
 
 4.0.0b2
 
-* #8818: autodoc: Super class having ``Any`` arguments causes nit-picky warning
+* #8818: autodoc: Super class having ``Any`` arguments causes nitpicky warning
 * #9095: autodoc: TypeError is raised on processing broken metaclass
 * #9110: autodoc: metadata of GenericAlias is not rendered as a reference in
   py37+
 * #9098: html: copy-range protection for doctests doesn't work in Safari
 * #9103: LaTeX: imgconverter: conversion runs even if not needed
-* #8127: py domain: Ellipsis in info-field-list causes nit-picky warning
+* #8127: py domain: Ellipsis in info-field-list causes nitpicky warning
 * #9121: py domain: duplicated warning is emitted when both canonical and its
   alias objects are defined on the document
 * #9023: More CSS classes on domain descriptions, see :ref:`nodes` for details.
@@ -3762,7 +3848,7 @@ Deprecated
 * The arguments of ``Epub3Builder.build_navigation_doc()``
 * The config variables
 
-  - :confval:`html_experimental_html5_writer`
+  - :confval:`!html_experimental_html5_writer`
 
 * The ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
   ``autodoc.DocstringSignatureMixin.get_doc()``,
@@ -3878,7 +3964,7 @@ Features added
 * #4611: epub: Show warning for duplicated ToC entries
 * #1851: Allow to omit an argument for :rst:dir:`code-block` directive.  If
   omitted, it follows :rst:dir:`highlight` or :confval:`highlight_language`
-* #4587: html: Add :confval:`html4_writer` to use old HTML4 writer
+* #4587: html: Add :confval:`!html4_writer` to use old HTML4 writer
 * #6016: HTML search: A placeholder for the search summary prevents search
   result links from changing their position when the search terminates.  This
   makes navigating search results easier.
@@ -4198,7 +4284,7 @@ Deprecated
 
 1.8.0b1
 
-* :confval:`source_parsers` is deprecated
+* :confval:`!source_parsers` is deprecated
 * :confval:`autodoc_default_flags` is deprecated
 * quickstart: ``--epub`` option becomes default, so it is deprecated
 * Drop function based directive support.  For now, Sphinx only supports class
@@ -6338,7 +6424,7 @@ Features added
 --------------
 
 * #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This
-  should be introduced with :confval:`source_parsers` feature. Thanks for Eric
+  should be introduced with :confval:`!source_parsers` feature. Thanks for Eric
   Holscher.
 
 
@@ -6405,7 +6491,7 @@ Bugs fixed
 * #2186: Fix LaTeX output of \mathbb in math
 * #1480, #2188: LaTeX: Support math in section titles
 * #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug
-* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii
+* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ASCII
   characters
 * #2193: Fix shutil.SameFileError if source directory and destination directory
   are same
@@ -6580,7 +6666,7 @@ Features added
 * The :confval:`source_suffix` config value can now be a list of multiple
   suffixes.
 * Add the ability to specify source parsers by source suffix with the
-  :confval:`source_parsers` config value.
+  :confval:`!source_parsers` config value.
 * #1675: A new builder, AppleHelpBuilder, has been added that builds Apple
   Help Books.
 

EXAMPLES.rst

@@ -64,7 +64,7 @@ Documentation using the classic theme
 * `DEAP <https://deap.readthedocs.io/>`__ (customized)
 * `Director <https://pythonhosted.org/director/>`__
 * `EZ-Draw <https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html>`__ (customized)
-* `Generic Mapping Tools (GMT) <https://gmt.soest.hawaii.edu/doc/latest/>`__ (customized)
+* `Generic Mapping Tools (GMT) <https://docs.generic-mapping-tools.org/latest/>`__ (customized)
 * `Genomedata <https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/>`__
 * `GetFEM <https://getfem.org/>`__ (customized)
 * `Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/>`__ (customized)
@@ -73,7 +73,7 @@ Documentation using the classic theme
 * `GSL Shell <https://www.nongnu.org/gsl-shell/>`__
 * `Hands-on Python Tutorial <http://anh.cs.luc.edu:80/python/hands-on/3.1/handsonHtml/>`__
 * `Kaa <https://freevo.github.io/kaa-base/>`__ (customized)
-* `Leo <https://leoeditor.com/>`__ (customized)
+* `Leo <https://leo-editor.github.io/leo-editor/>`__ (customized)
 * `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`__ (customized)
 * `MediaGoblin <https://mediagoblin.readthedocs.io/>`__ (customized)
 * `mpmath <https://mpmath.org/doc/current/>`__
@@ -91,10 +91,10 @@ Documentation using the classic theme
 * `Python 2 <https://docs.python.org/2/>`__
 * `Python 3 <https://docs.python.org/3/>`__ (customized)
 * `Python Packaging Authority <https://www.pypa.io/>`__ (customized)
-* `Ring programming language <https://ring-lang.sourceforge.net/doc/>`__ (customized)
+* `Ring programming language <https://ring-lang.github.io/doc1.20/>`__ (customized)
 * `SageMath <https://doc.sagemath.org/>`__ (customized)
 * `Segway <https://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html>`__
-* `simuPOP <https://simupop.sourceforge.net/manual_release/build/userGuide.html>`__ (customized)
+* `simuPOP <https://bopeng.github.io/simuPOP/>`__ (customized)
 * `SymPy <https://docs.sympy.org/>`__
 * `TurboGears <https://turbogears.readthedocs.io/>`__ (customized)
 * `tvtk <https://docs.enthought.com/mayavi/tvtk/>`__
@@ -120,7 +120,6 @@ Documentation using the sphinxdoc theme
 * `Python Wild Magic <https://vmlaker.github.io/pythonwildmagic/>`__ (customized)
 * `RDKit <https://www.rdkit.org/docs/>`__
 * `Reteisi <https://www.reteisi.org/contents.html>`__ (customized)
-* `Sqlkit <https://sqlkit.argolinux.org/>`__ (customized)
 * `Turbulenz <http://docs.turbulenz.com/>`__
 
 Documentation using the nature theme
@@ -183,7 +182,7 @@ Documentation using sphinx_rtd_theme
 * `DNF <https://dnf.readthedocs.io/>`__
 * `Distro Tracker <https://qa.pages.debian.net/distro-tracker/>`__
 * `Django-cas-ng <https://djangocas.dev/docs/>`__
-* `dj-stripe <https://dj-stripe.readthedocs.io/>`__
+* `dj-stripe <https://dj-stripe.github.io/dj-stripe/>`__
 * `edX <https://docs.edx.org/>`__
 * `Electrum <https://docs.electrum.org/>`__
 * `ESWP3 <https://eswp3.readthedocs.io/>`__
@@ -262,7 +261,7 @@ Documentation using sphinx_rtd_theme
 * `Releases Sphinx extension <https://releases.readthedocs.io/>`__
 * `Qtile <https://docs.qtile.org/>`__
 * `Quex <https://quex.sourceforge.net/doc/html/main.html>`__
-* `QuTiP <https://qutip.org/docs/latest/>`__
+* `QuTiP <https://qutip.readthedocs.io/en/latest/>`__
 * `Sawtooth <https://sawtooth.splinter.dev/docs>`__
 * `Scapy <https://scapy.readthedocs.io/>`__
 * `SimGrid <https://simgrid.org/doc/latest/>`__