Merge branch 'master' into literallyinclude-options

.github/workflows/builddoc.yml

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

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/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.

doc/usage/restructuredtext/directives.rst

@@ -117,7 +117,7 @@ The ``toctree`` directive is the central element.
    .. versionchanged:: 0.6
       Added support for external links and "self" references.
 
-   .. rubric:: options
+   .. rubric:: Options
 
    .. rst:directive:option:: class: class names
       :type: a list of class names, separated by spaces
@@ -562,6 +562,27 @@ Presentational
    A rubric is like an informal heading that doesn't correspond to the document's structure,
    i.e. it does not create a table of contents node.
 
+   .. note::
+
+      If the *title* of the rubric is "Footnotes" (or the selected language's
+      equivalent), this rubric is ignored by the LaTeX writer, since it is
+      assumed to only contain footnote definitions and therefore would create an
+      empty heading.
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: class: class names
+      :type: a list of class names, separated by spaces
+
+      Assign `class attributes`_.
+      This is a :dudir:`common option <common-options>`.
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      An implicit target name that can be referenced using :rst:role:`ref`.
+      This is a :dudir:`common option <common-options>`.
+
    .. rst:directive:option:: heading-level: n
       :type: number from 1 to 6
 
@@ -572,12 +593,6 @@ Presentational
       or as the corresponding non-numbered sectioning command for LaTeX
       (see :confval:`latex_toplevel_sectioning`).
 
-   .. note::
-
-      If the *title* of the rubric is "Footnotes" (or the selected language's
-      equivalent), this rubric is ignored by the LaTeX writer, since it is
-      assumed to only contain footnote definitions and therefore would create an
-      empty heading.
 
 .. rst:directive:: centered
 
@@ -594,17 +609,22 @@ Presentational
    compact list by either distributing more than one item horizontally, or
    reducing spacing between items, depending on the builder.
 
-   For builders that support the horizontal distribution, there is a ``columns``
-   option that specifies the number of columns; it defaults to 2.  Example::
+   .. rubric:: Options
+
+   .. rst:directive:option:: columns: n
+      :type: int
+
+      The number of columns; defaults to 2.
+      For example::
 
-      .. hlist::
-         :columns: 3
+         .. hlist::
+            :columns: 3
 
-         * A list of
-         * short items
-         * that should be
-         * displayed
-         * horizontally
+            * A list of
+            * short items
+            * that should be
+            * displayed
+            * horizontally
 
    .. versionadded:: 0.6
 
@@ -678,7 +698,7 @@ __ https://pygments.org/docs/lexers
    As discussed previously, *language* can be any lexer alias supported by
    Pygments.
 
-   .. rubric:: options
+   .. rubric:: Options
 
    .. rst:directive:option:: linenothreshold: threshold
       :type: number (optional)
@@ -723,7 +743,7 @@ __ https://pygments.org/docs/lexers
    .. versionchanged:: 2.0
       The ``language`` argument becomes optional.
 
-   .. rubric:: options
+   .. rubric:: Options
 
    .. rst:directive:option:: linenos
       :type: no value
@@ -1112,19 +1132,26 @@ Glossary
    text only have "term" part. In this case, translated "localized term" will be
    categorized in "key" group.
 
-   .. versionadded:: 0.6
-      You can now give the glossary directive a ``:sorted:`` flag that will
-      automatically sort the entries alphabetically.
 
    .. versionchanged:: 1.1
       Now supports multiple terms and inline markup in terms.
 
    .. versionchanged:: 1.4
       Index key for glossary term should be considered *experimental*.
 
-   .. versionchanged:: 4.4
-      In internationalized documentation, the ``:sorted:`` flag sorts
-      according to translated terms.
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: sorted
+
+      Sort the entries alphabetically.
+
+      .. versionadded:: 0.6
+
+      .. versionchanged:: 4.4
+         In internationalized documentation, sort according to translated terms.
+
+
 
 Meta-information markup
 -----------------------
@@ -1273,7 +1300,7 @@ mainly contained in information units, such as the language reference.
    .. versionchanged:: 1.1
       Added ``see`` and ``seealso`` types, as well as marking main entries.
 
-   .. rubric:: options
+   .. rubric:: Options
 
    .. rst:directive:option:: name: a label for hyperlink
       :type: text
@@ -1477,23 +1504,45 @@ or use Python raw strings (``r"raw"``).
 
       .. math:: (a + b)^2 = a^2 + 2ab + b^2
 
-   Normally, equations are not numbered.  If you want your equation to get a
-   number, use the ``label`` option.  When given, it selects an internal label
-   for the equation, by which it can be cross-referenced, and causes an equation
-   number to be issued.  See :rst:role:`eq` for an example.  The numbering
-   style depends on the output format.
+   .. rubric:: Options
 
-   There is also an option ``nowrap`` that prevents any wrapping of the given
-   math in a math environment.  When you give this option, you must make sure
-   yourself that the math is properly set up.  For example::
+   .. rst:directive:option:: class: class names
+      :type: a list of class names, separated by spaces
 
-      .. math::
-         :nowrap:
+      Assign `class attributes`_.
+      This is a :dudir:`common option <common-options>`.
+
+      .. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      An implicit target name that can be referenced using :rst:role:`ref`.
+      This is a :dudir:`common option <common-options>`.
+
+   .. rst:directive:option:: label: label
+      :type: text
+
+      Normally, equations are not numbered.  If you want your equation to get a
+      number, use the ``label`` option.  When given, it selects an internal label
+      for the equation, by which it can be cross-referenced, and causes an equation
+      number to be issued.  See :rst:role:`eq` for an example.  The numbering
+      style depends on the output format.
+
+   .. rst:directive:option:: nowrap
+
+      Prevent wrapping of the given math in a math environment.
+      When you give this option, you must make sure
+      yourself that the math is properly set up.
+      For example::
+
+         .. math::
+            :nowrap:
 
-         \begin{eqnarray}
-            y    & = & ax^2 + bx + c \\
-            f(x) & = & x^2 + 2xy + y^2
-         \end{eqnarray}
+            \begin{eqnarray}
+               y    & = & ax^2 + bx + c \\
+               f(x) & = & x^2 + 2xy + y^2
+            \end{eqnarray}
 
 .. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex