jupyter-book

jupyter-book copied to clipboard

Is your feature request related to a problem? Please describe.

If the code fails to execute, the user faces

WARNING: Execution Failed with traceback saved in _build/html/reports/content.log

This is inefficient in a CI environment, see also https://twitter.com/minrk/status/1304317642283548672

Describe the solution you'd like

Either a configurable option to print all jupyterbook errors/warnings to stderr, or always printing to stderr.

Which is exactly why in myst-nb there is the execution_show_tb options 😉 see: https://myst-nb.readthedocs.io/en/latest/use/start.html#myst-nb-configuration-options, and what I use on ReadTheDocs: https://github.com/executablebooks/MyST-NB/blob/446cf0d269a0906eacc1b88b418c7bce40ee4cee/docs/conf.py#L97

Since jupyter-book aims to be the one-size-fits-all-no-tweaking-required, should this perhaps be the default behavior?

should this perhaps be the default behavior?

No, but there could easily be a CLI flag added

or probably better it could be associated with one of the existing CLI flags, i.e. the verbosity level (set to True if verbose>1, which equates to jb build -vv)

should this perhaps be the default behavior?

No

Can you elaborate? Under which conditions is having the traceback in the file the behavior preferred by the user?

Well basically, why wouldn't you want the behaviour to be: show little output on jb build, show more output on jb -v, show even more output on jb -vv?

If something goes wrong in a way that is likely relevant for the user, and leads to negative consequences if overlooked, then it should at least be hard to miss, or just lead to a failed build.

Which is exactly why it suggests in the documentation running with the standard sphinx flags: jupyter-book build -W -n --keep-going mybookname/ https://jupyterbook.org/start/build.html

-W converts warnings—so potentially unimportant problems—to errors. I'm suggesting that failed execution should be an error and should print the traceback. The severity of code failing to execute is higher than e.g. that of an orphan document.

For new users (like me), it's hard to figure out the solution, as an alternative to setting it as default, the error:

ERROR: Execution Failed with traceback saved in /path/to.log

Could say something like:

ERROR: Execution Failed with traceback saved in /path/to.log - to print the traceback set execution_show_tb to True in _config.yml (under sphinx.config)