Merge branch 'master' into latex_DUrole

Author: jfbu

.flake8

@@ -33,5 +33,6 @@ exclude =
     doc/usage/extensions/example*.py,
 per-file-ignores =
     doc/conf.py:W605
+    sphinx/events.py:E704,
     tests/test_extensions/ext_napoleon_pep526_data_google.py:MLL001,
     tests/test_extensions/ext_napoleon_pep526_data_numpy.py:MLL001,

.github/workflows/builddoc.yml

@@ -44,4 +44,3 @@ jobs:
         --jobs=auto
         --show-traceback
         --fail-on-warning
-        --keep-going

.github/workflows/lint.yml

@@ -24,12 +24,17 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+    - name: Get Ruff version from pyproject.toml
+      run: |
+        RUFF_VERSION=$(awk -F'[="]' '/\[project\.optional-dependencies\]/ {p=1} /ruff/ {if (p) print $4}' pyproject.toml)
+        echo "RUFF_VERSION=$RUFF_VERSION" >> $GITHUB_ENV
+
     - name: Install Ruff
       run: >
-        RUFF_VERSION=$(awk -F'[="]' '/\[project\.optional-dependencies\]/ {p=1} /ruff/ {if (p) print $4}' pyproject.toml)
         curl --no-progress-meter --location --fail
         --proto '=https' --tlsv1.2
-        "https://astral.sh/ruff/${RUFF_VERSION}/install.sh"
+        --write-out "%{stderr}Downloaded: %{url}\n"
+        "https://astral.sh/ruff/$RUFF_VERSION/install.sh"
         | sh
 
     - name: Lint with Ruff

.github/workflows/nodejs.yml

@@ -23,11 +23,14 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+env:
+  FORCE_COLOR: "1"
+
 jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      node-version: "16"
+      node-version: "20"
 
     steps:
     - uses: actions/checkout@v4
@@ -37,5 +40,4 @@ jobs:
         node-version: ${{ env.node-version }}
         cache: "npm"
     - run: npm install
-    - name: Run headless test
-      run: xvfb-run -a npm test
+    - run: npm test

CHANGES.rst

@@ -30,6 +30,14 @@ Features added
   output files.
 * #12474: Support type-dependent search result highlighting via CSS.
   Patch by Tim Hoffmann.
+* #12743: No longer exit on the first warning when
+  :option:`--fail-on-warning <sphinx-build --fail-on-warning>` is used.
+  Instead, exit with a non-zero status if any warnings were generated
+  during the build.
+  Patch by Adam Turner.
+* #12743: Add :option:`sphinx-build --exception-on-warning`,
+  to raise an exception when warnings are emitted during the build.
+  Patch by Adam Turner and Jeremy Maitin-Shepard.
 
 Bugs fixed
 ----------

doc/conf.py

@@ -186,19 +186,24 @@
     ('js:func', 'number'),
     ('js:func', 'string'),
     ('py:attr', 'srcline'),
+    ('py:class', '_ConfigRebuild'),  # sphinx.application.Sphinx.add_config_value
     ('py:class', '_StrPath'),  # sphinx.environment.BuildEnvironment.doc2path
     ('py:class', 'Element'),  # sphinx.domains.Domain
     ('py:class', 'Documenter'),  # sphinx.application.Sphinx.add_autodocumenter
     ('py:class', 'IndexEntry'),  # sphinx.domains.IndexEntry
+    ('py:class', 'Lexer'),  # sphinx.application.Sphinx.add_lexer
     ('py:class', 'Node'),  # sphinx.domains.Domain
     ('py:class', 'NullTranslations'),  # gettext.NullTranslations
+    ('py:class', 'Path'),  # sphinx.application.Sphinx.connect
     ('py:class', 'RoleFunction'),  # sphinx.domains.Domain
     ('py:class', 'RSTState'),  # sphinx.utils.parsing.nested_parse_to_nodes
     ('py:class', 'Theme'),  # sphinx.application.TemplateBridge
     ('py:class', 'SearchLanguage'),  # sphinx.application.Sphinx.add_search_language
     ('py:class', 'StringList'),  # sphinx.utils.parsing.nested_parse_to_nodes
     ('py:class', 'system_message'),  # sphinx.utils.docutils.SphinxDirective
     ('py:class', 'TitleGetter'),  # sphinx.domains.Domain
+    ('py:class', 'todo_node'),  # sphinx.application.Sphinx.connect
+    ('py:class', 'Transform'),  # sphinx.application.Sphinx.add_transform
     ('py:class', 'XRefRole'),  # sphinx.domains.Domain
     ('py:class', 'docutils.nodes.Element'),
     ('py:class', 'docutils.nodes.Node'),
@@ -210,6 +215,7 @@
     ('py:class', 'docutils.parsers.rst.states.Inliner'),
     ('py:class', 'docutils.transforms.Transform'),
     ('py:class', 'nodes.NodeVisitor'),
+    ('py:class', 'nodes.TextElement'),  # sphinx.application.Sphinx.connect
     ('py:class', 'nodes.document'),
     ('py:class', 'nodes.reference'),
     ('py:class', 'pygments.lexer.Lexer'),

doc/extdev/event_callbacks.rst

@@ -107,10 +107,10 @@ Here is a more detailed list of these events.
 
    :param app: :class:`.Sphinx`
    :param env: :class:`.BuildEnvironment`
-   :param added: ``set[str]``
-   :param changed: ``set[str]``
-   :param removed: ``set[str]``
-   :returns: ``list[str]`` of additional docnames to re-read
+   :param added: ``Set[str]``
+   :param changed: ``Set[str]``
+   :param removed: ``Set[str]``
+   :returns: ``Sequence[str]`` of additional docnames to re-read
 
    Emitted when the environment determines which source files have changed and
    should be re-read.

doc/internals/contributing.rst

@@ -263,7 +263,7 @@ To build the documentation, run the following command:
 
 .. code-block:: shell
 
-   sphinx-build -M html ./doc ./build/sphinx --fail-on-warning --keep-going
+   sphinx-build -M html ./doc ./build/sphinx --fail-on-warning
 
 This will parse the Sphinx documentation's source files and generate HTML for
 you to preview in :file:`build/sphinx/html`.

doc/man/sphinx-build.rst

@@ -43,7 +43,7 @@ Options
       the source and output directories, before any other options are passed.
       For example::
 
-          sphinx-build -M html ./source ./build --fail-on-warning --keep-going
+          sphinx-build -M html ./source ./build --fail-on-warning
 
    The *make-mode* provides the same build functionality as
    a default :ref:`Makefile or Make.bat <makefile_options>`,
@@ -253,20 +253,35 @@ Options
 
 .. option:: -W, --fail-on-warning
 
-   Turn warnings into errors.  This means that the build stops at the first
-   warning and ``sphinx-build`` exits with exit status 1.
+   Turn warnings into errors.
+   This means that :program:`sphinx-build` exits with exit status 1
+   if any warnings are generated during the build.
 
    .. versionchanged:: 7.3
       Add ``--fail-on-warning`` long option.
+   .. versionchanged:: 8.1
+      :program:`sphinx-build` no longer exits on the first warning,
+      but instead runs the entire build and exits with exit status 1
+      if any warnings were generated.
+      This behaviour was previously enabled with :option:`--keep-going`.
 
 .. option:: --keep-going
 
-   Only applicable whilst using :option:`--fail-on-warning`,
-   which by default exits :program:`sphinx-build` on the first warning.
+   From Sphinx 8.1, :option:`!--keep-going` is always enabled.
+   Previously, it was only applicable whilst using :option:`--fail-on-warning`,
+   which by default exited :program:`sphinx-build` on the first warning.
    Using :option:`!--keep-going` runs :program:`!sphinx-build` to completion
    and exits with exit status 1 if errors are encountered.
 
    .. versionadded:: 1.8
+   .. versionchanged:: 8.1
+      :program:`sphinx-build` no longer exits on the first warning,
+      meaning that in effect :option:`!--fail-on-warning` is always enabled.
+      The option is retained for compatibility, but may be removed at some
+      later date.
+
+   .. xref RemovedInSphinx10Warning: deprecate this option in Sphinx 10
+                                     or no earlier than 2026-01-01.
 
 .. option:: -T, --show-traceback
 
@@ -287,6 +302,13 @@ Options
    .. versionchanged:: 7.3
       Add ``--pdb`` long option.
 
+.. option:: --exception-on-warning
+
+   Raise an exception when a warning is emitted during the build.
+   This can be useful in combination with :option:`--pdb` to debug warnings.
+
+   .. versionadded:: 8.1
+
 .. option:: -h, --help, --version
 
    Display usage summary or Sphinx version.

doc/usage/extensions/autodoc.rst

@@ -770,6 +770,10 @@ There are also config values that you can set:
    If ``False`` is given, autodoc forcedly suppresses the error if the imported
    module emits warnings.  By default, ``True``.
 
+   .. versionchanged:: 8.1
+      This option now has no effect as :option:`!--fail-on-warning`
+      no longer exits early.
+
 .. confval:: autodoc_inherit_docstrings
 
    This value controls the docstrings inheritance.