Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new print_traceback configuration option #13163

Open
wants to merge 6 commits into
base: master
Choose a base branch
from

Conversation

kdeldycke
Copy link

@kdeldycke kdeldycke commented Dec 3, 2024

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

Purpose

  • Improve in-situ debuguability of Sphinx.
  • Improve bug reporting of third-party extensions.

Detail

For instance, when Sphinx is run in CI/CD (like GitHub actions workflows), we do not have access to the file-system. So when Sphinx encounter a fatal internal error, it just print the last frace of the traceback and dump the full traceback in a local temporary file.

This can produce error logs as uninformative as:

(...)
Exception occurred:
  File "<docs>", line 3, in <module>
AssertionError
The full traceback has been saved in /tmp/sphinx-err-wjogkybw.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

So by always printing the full traceback, this PR will improve identification of root causes, especially if they're coming from third-party plugins and extensions. I expect this change to have the nice side effect of improving bug reports to the community.

@kdeldycke kdeldycke force-pushed the print-full-traceback branch 11 times, most recently from 882f848 to 0ececc0 Compare December 3, 2024 10:23
Allow the full traceback to be printed when Sphinx encounters an
internal fatal error.
@kdeldycke kdeldycke force-pushed the print-full-traceback branch from 0ececc0 to 6494db7 Compare December 3, 2024 10:25
# Conflicts:
#	CHANGES.rst
#	sphinx/config.py
# Conflicts:
#	sphinx/_cli/util/errors.py
#	sphinx/util/exceptions.py
@AA-Turner AA-Turner added type:enhancement enhance or introduce a new feature api:cmdline internals:config labels Jan 3, 2025
@AA-Turner AA-Turner added this to the 8.2.0 milestone Jan 3, 2025
Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the very nice PR @kdeldycke, and sorry it has taken a month to review.

The only real question I have is on design -- is a config option the right choice here? Should we use an environment variable or command-line flag instead?

In other words, what are the scenarios for disabling this feature, and when are people most likely to do so? I am half-minded to unconditionally enable it, but there might be complaints of overly-long console output.

A

# Conflicts:
#	CHANGES.rst
#	sphinx/_cli/util/errors.py
#	sphinx/cmd/build.py
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api:cmdline internals:config type:enhancement enhance or introduce a new feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants