Add new print_traceback configuration option

Allow the full traceback to be printed when Sphinx encounters an
internal fatal error.

CHANGES.rst

@@ -18,6 +18,11 @@ Deprecated
 Features added
 --------------
 
+* #13163: Add the :confval:`print_traceback` configuration option
+  to control whether tracebacks are printed in full when Sphinx
+  encounters an internal error.
+  Patch by Kevin Deldycke.
+
 Bugs fixed
 ----------
 

doc/usage/configuration.rst

@@ -317,6 +317,21 @@ General configuration
    (or, if translation is enabled with :confval:`language`,
    an equivalent format for the selected locale).
 
+.. confval:: print_traceback
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   If :code-py:`False`, the full traceback will not be printed when Sphinx
+   encounters an internal fatal error. It will instead print a short message
+   and exit.
+
+   .. note::
+
+      Whatever the setting is set to, the traceback is always saved in a
+      temporary file named ``sphinx-err-xxxxxxxx.log``.
+
+   .. versionadded:: 8.2.0
+
 
 Options for figure numbering
 ----------------------------

sphinx/_cli/util/errors.py

@@ -59,7 +59,7 @@ def error_info(messages: str, extensions: str, traceback: str) -> str:
 """
 
 
-def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
+def save_traceback(app: Sphinx | None, exc: BaseException) -> tuple[str, str]:
     """Save the given exception's traceback in a temporary file."""
     if isinstance(exc, SphinxParallelError):
         exc_format = '(Error in parallel process)\n' + exc.traceback
@@ -78,12 +78,14 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
             if ext.version != 'builtin'
         )
 
+    output = error_info(last_msgs, exts_list, exc_format)
+
     with tempfile.NamedTemporaryFile(
         suffix='.log', prefix='sphinx-err-', delete=False
     ) as f:
-        f.write(error_info(last_msgs, exts_list, exc_format).encode('utf-8'))
+        f.write(output.encode('utf-8'))
 
-    return f.name
+    return f.name, output
 
 
 def handle_exception(
@@ -164,7 +166,9 @@ def print_red(*values: str) -> None:
 
     print_red(__('Exception occurred:'))
     print_err(formatted_tb)
-    traceback_info_path = save_traceback(app, exception)
+    traceback_info_path, traceback_output = save_traceback(app, exception)
+    if not app or app.config.print_traceback:
+        print_err(traceback_output)
     print_err(__('The full traceback has been saved in:'))
     print_err(traceback_info_path)
     print_err()

sphinx/cmd/build.py

@@ -72,7 +72,9 @@ def handle_exception(
         elif isinstance(exception, UnicodeError):
             print(red(__('Encoding error:')), file=stderr)
             print(terminal_safe(str(exception)), file=stderr)
-            tbpath = save_traceback(app, exception)
+            tbpath, tboutput = save_traceback(app, exception)
+            if not app or app.config.print_traceback:
+                print(tboutput)
             print(
                 red(
                     __(
@@ -102,7 +104,9 @@ def handle_exception(
         else:
             print(red(__('Exception occurred:')), file=stderr)
             print(format_exception_cut_frames().rstrip(), file=stderr)
-            tbpath = save_traceback(app, exception)
+            tbpath, tboutput = save_traceback(app, exception)
+            if not app or app.config.print_traceback:
+                print(tboutput)
             print(
                 red(
                     __(

sphinx/config.py

@@ -207,6 +207,7 @@ class Config:
         'today': _Opt('', 'env', ()),
         # the real default is locale-dependent
         'today_fmt': _Opt(None, 'env', frozenset((str,))),
+        'print_traceback': _Opt(True, 'env', ()),
 
         'language': _Opt('en', 'env', frozenset((str,))),
         'locale_dirs': _Opt(['locales'], 'env', ()),

sphinx/util/exceptions.py

@@ -12,7 +12,7 @@
     from sphinx.application import Sphinx
 
 
-def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
+def save_traceback(app: Sphinx | None, exc: BaseException) -> tuple[str, str]:
     """Save the given exception's traceback in a temporary file."""
     import platform
 
@@ -40,10 +40,7 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
             if ext.version != 'builtin'
         )
 
-    with NamedTemporaryFile(
-        'w', encoding='utf-8', suffix='.log', prefix='sphinx-err-', delete=False
-    ) as f:
-        f.write(f"""\
+    output = f"""\
 # Platform:         {sys.platform}; ({platform.platform()})
 # Sphinx version:   {sphinx.__display_version__}
 # Python version:   {platform.python_version()} ({platform.python_implementation()})
@@ -59,8 +56,13 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
 
 # Traceback:
 {exc_format}
-""")
-    return f.name
+"""
+
+    with NamedTemporaryFile(
+        'w', encoding='utf-8', suffix='.log', prefix='sphinx-err-', delete=False
+    ) as f:
+        f.write(output)
+    return f.name, output
 
 
 def format_exception_cut_frames(x: int = 1) -> str: