DOC: Suppress IPython output in examples and tutorials where not needed #23978
Conversation
By default, sphinx-gallery captures the last output of each code block and shows it in the generated html in yellow boxes. Especially in tutorials with a frequently interleaving code and text blocks this may appear confusing and reduces readability. In some cases, however, the output is desired (although it could always be replaced by printing). The global configuration is now changed to "capture nothing", for one tutorial with multiple desired outputs this is overridden in the file to show the output and in other cases with just one desired output it's converted to a call to print().
|
I am very surprised that we only had ~2 cases where the output was valuable and intentials. I'm inclined to merge but not back port this so we have a while for any issues to be found in the devdocs. |
Me too - if I had known earlier I wouldn't have made sphinx-gallery/sphinx-gallery#891. It turned out, however, that practically in all cases, where the output is intentional, it was already produced by |
|
I'm also surprised, but this
makes sense.
Do we read the devdocs so thoroughly that we would find possible issues? While I do a lot of docs stuff, I would not claim for me that I would find a significant fraction of such issues if they existed. I therefore would be happy to backport. |
…s and tutorials where not needed
…978-on-v3.6.x Backport PR #23978 on branch v3.6.x (DOC: Suppress IPython output in examples and tutorials where not needed)
PR Summary
By default, sphinx-gallery captures the last output of each code block and shows it in the generated html in yellow boxes. Especially in tutorials with frequently interleaving code and text blocks this may appear confusing and reduces readability. In some cases, however, the output is desired (although it could always be replaced by printing).
The global configuration is now changed to "capture nothing", for one tutorial with multiple desired outputs this is overridden in the file to show the output and in other cases with just one desired output it's converted to a call to print().
(I went through all the examples and tutorials by searching the generated rst files for
.. rst-class:: sphx-glr-script-outto see if we need the generated output, hopefully I didn't overlook some desired output)This PR addresses this #21794 (comment):
PR Checklist
Tests and Styling
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).