Allow --pdb option to also debug warnings

Previously, warnings emitted during reading and writing were deferred,
which made --pdb ineffective for debugging them.

With this change, warnings are no longer deferred when --pdb and
--fail-on-warning are both specified.

CHANGES.rst

@@ -13,6 +13,9 @@ Deprecated
 Features added
 --------------
 
+* #12727: build: Allow --pdb to debug warnings when --fail-on-warning is specified.
+  Patch by Jeremy Maitin-Shepard.
+
 Bugs fixed
 ----------
 

sphinx/builders/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import codecs
+import contextlib
 import pickle
 import re
 import time
@@ -313,7 +314,9 @@ def build(
             logger.info(bold(__('building [%s]: ')) + summary, self.name)
 
         # while reading, collect all warnings from docutils
-        with logging.pending_warnings():
+        with contextlib.ExitStack() as exit_stack:
+            if not self.app.pdb or not self.app.warningiserror:
+                exit_stack.enter_context(logging.pending_warnings())
             updated_docnames = set(self.read())
 
         doccount = len(updated_docnames)
@@ -613,7 +616,9 @@ def write(
             self._write_serial(sorted(docnames))
 
     def _write_serial(self, docnames: Sequence[str]) -> None:
-        with logging.pending_warnings():
+        with contextlib.ExitStack() as exit_stack:
+            if not self.app.pdb or not self.app.warningiserror:
+                exit_stack.enter_context(logging.pending_warnings())
             for docname in status_iterator(docnames, __('writing output... '), "darkgreen",
                                            len(docnames), self.app.verbosity):
                 self.app.phase = BuildPhase.RESOLVING