Merge branch 'refs/heads/master' into pr-11916-followup/rename-template-files

# Conflicts:
#	sphinx/ext/apidoc.py

Author: AA-Turner

.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

@@ -13,6 +13,14 @@ Deprecated
 Features added
 --------------
 
+* #12456: Add :option:`sphinx-autogen --remove-old` option.
+  Patch by Chris Sewell.
+* #12448: Add :option:`sphinx-apidoc --remove-old` option.
+  Patch by Chris Sewell.
+* #12358: Add :attr:`.Sphinx.fresh_env_used`.
+  Patch by Chris Sewell.
+* #12361: Add :attr:`.BuildEnvironment.parser`.
+  Patch by Chris Sewell.
 * #11165: Support the `officially recommended`_ ``.jinja`` suffix for template
   files.
   Patch by James Addison and Adam Turner
@@ -21,6 +29,23 @@ Features added
 * Flatten ``Union[Literal[T], Literal[U], ...]`` to ``Literal[T, U, ...]``
   when turning annotations into strings.
   Patch by Adam Turner.
+* #12329: Add detection of ambiguous ``std:label`` and ``std:term`` references during
+  loading and resolution of Intersphinx targets.
+  Patch by James Addison.
+* #12319: ``sphinx.ext.extlinks``: Add ``extlink-{name}`` CSS class to links.
+  Patch by Hugo van Kemenade.
+* #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.
+
 
 Bugs fixed
 ----------
@@ -36,10 +61,38 @@ 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: :confval:`root_doc` is synchronized with :confval:`master_doc`
+  so that if either of the two values is modified, the other reflects that
+  modification. It is still recommended to use :confval:`root_doc`.
+  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.
+
+Improvements
+------------
+
+* #12387: Improve CLI progress message, when copying assets.
+  Patch by Bénédikt Tran.
+* #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
 
 Testing
 -------
 
+* karma: refactor HTML search tests to use fixtures generated by Sphinx.
+  Patch by James Addison.
+
 Release 7.3.7 (released Apr 19, 2024)
 =====================================
 

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/>`__

doc/_static/diagrams/sphinx_build_flow.dot

@@ -0,0 +1,47 @@
+// UML for the standard Sphinx build workflow
+
+digraph build {
+    graph [
+        rankdir=LR
+    ];
+    node [
+        shape=rect
+        style=rounded
+    ];
+
+    "Sphinx" [
+        shape=record
+        label = "Sphinx | <init> __init__ | <build> build"
+    ];
+    "Sphinx":init -> "Builder.init";
+    "Sphinx":build -> "Builder.build_all";
+    "Sphinx":build -> "Builder.build_specific";
+    "Builder.build_update" [
+        shape=record
+        label = "<p1> Builder.build_update | Builder.get_outdated_docs"
+    ];
+    "Sphinx":build -> "Builder.build_update":p1 ;
+
+    "Builder.build_all" -> "Builder.build";
+    "Builder.build_specific" -> "Builder.build";
+    "Builder.build_update":p1 -> "Builder.build";
+
+    "Builder.build" -> "Builder.read";
+    "Builder.write" [
+        shape=record
+        label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel"
+    ];
+    "Builder.build" -> "Builder.write";
+    "Builder.build" -> "Builder.finish";
+
+    "Builder.read" -> "Builder.read_doc";
+    "Builder.read_doc" -> "Builder.write_doctree";
+
+    "Builder.write":p1 -> "Builder.prepare_writing";
+    "Builder.write":p1 -> "Builder.copy_assets";
+    "Builder.write":p1 -> "Builder.write_doc";
+
+    "Builder.write_doc" -> "Builder.get_relative_uri";
+
+    "Builder.get_relative_uri" -> "Builder.get_target_uri";
+}

doc/_static/diagrams/sphinx_core_events_flow.dot

@@ -0,0 +1,123 @@
+// A flow graph of the Sphinx build process, highlighting event callbacks
+
+digraph events {
+    graph [
+        rankdir=TB
+    ];
+    node [
+        shape=rect
+        style=rounded
+    ];
+    "Sphinx" [
+        shape=record
+        label = "<init> Sphinx.__init__() | <build> Sphinx.build()"
+    ];
+
+    // During initialization
+    "config-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Sphinx":init -> "config-inited";
+    "builder-inited"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Sphinx":init -> "builder-inited";
+
+    // During build
+    "Builder" [label = "Builder.build()"]
+    "Sphinx":build -> "Builder";
+    "Builder.build" [
+        shape=record
+        label = "
+            <before_read> before read |
+            <read> read |
+            <after_read> after read |
+            <write> write |
+            <finalize> finalize"
+    ];
+    "Builder" -> "Builder.build";
+
+    "env-get-outdated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":before_read -> "env-get-outdated";
+    remove_each_doc [shape="ellipse", label="for removed"];
+    "Builder.build":before_read -> "remove_each_doc";
+    "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "remove_each_doc" -> "env-purge-doc";
+    "env-before-read-docs"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":before_read -> "env-before-read-docs";
+
+    // during read phase
+    "Builder.read" [label = "Builder.read()"]
+    "Builder.build":read -> "Builder.read";
+    read_each_doc [shape="ellipse", label="for added | changed"];
+    "Builder.read" -> "read_each_doc";
+    merge_each_process [
+    shape="ellipse", label="for each process\n(parallel only)"
+    ];
+    "Builder.read" -> merge_each_process;
+    "env-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.read" -> "env-updated"
+
+    // during read phase, for each document/process
+    "env-purge-doc"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "env-purge-doc";
+    "source-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "source-read";
+    "Include" [label="Include\ndirective"]
+    "read_each_doc" -> "Include";
+    "include-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Include" -> "include-read";
+    "ObjectDescription" [label="ObjectDescription\ndirective"]
+    "read_each_doc" -> "ObjectDescription";
+    "object-description-transform"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "ObjectDescription" -> "object-description-transform";
+    "doctree-read"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "read_each_doc" -> "doctree-read";
+    "env-merge-info"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "merge_each_process" -> "env-merge-info";
+
+    // after read phase
+    "env-get-updated"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":after_read -> "env-get-updated";
+    if_read_changes [shape="diamond", label="if changed\ndocuments"];
+    "Builder.build":after_read -> if_read_changes;
+    if_read_changes -> "cache the\nBuild.Environment";
+    "env-check-consistency"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    if_read_changes -> "env-check-consistency";
+
+    // during write phase
+    "Builder.write" [label = "Builder.write()"]
+    "Builder.build":write -> "Builder.write";
+    write_each_doc [shape="ellipse", label="for updated"];
+    "Builder.write" -> write_each_doc;
+    "ReferenceResolver" [
+    label="ReferenceResolver\nPost-transform"
+    ]
+    write_each_doc -> "ReferenceResolver";
+    "missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    ReferenceResolver -> "missing-reference";
+    "warn-missing-reference"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    ReferenceResolver -> "warn-missing-reference";
+    "HyperlinkCollector" [
+    label="HyperlinkCollector\nPost-transform"
+    ]
+    write_each_doc -> "HyperlinkCollector";
+    "linkcheck-process-uri"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    HyperlinkCollector -> "linkcheck-process-uri";
+    "doctree-resolved"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    write_each_doc -> "doctree-resolved";
+    "html-page-context"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    write_each_doc -> "html-page-context";
+
+    // html only
+    "html-collect-pages"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":finalize -> "html-collect-pages";
+
+    // finalize build
+    "build-finished"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":finalize -> "build-finished";
+
+    // constrain layout ordering
+    {rank=same "config-inited" "builder-inited"};
+    {rank=same; "env-get-outdated" "env-before-read-docs" "env-get-updated"};
+    {rank=same; "env-purge-doc" "source-read" "doctree-read", "merge_each_process"};
+    {rank=same; "env-updated" "env-check-consistency"};
+    {rank=same; "env-merge-info" "Builder.write"};
+    {rank=max; "build-finished"};
+}