Automatically executing notebooks during the Sphinx build process is an important feature of
nbsphinx. However, there are a few use cases where pre-executing a notebook and storing the outputs might be preferable. Storing any output will, by default, stop
nbsphinx from executing the notebook.
If you are doing some very time-consuming computations, it might not be feasible to re-execute the notebook every time you build your Sphinx documentation.
So just do it once – when you happen to have the time – and then just keep the output.
%time time.sleep(60 * 60) 6 * 7
CPU times: user 160 ms, sys: 56 ms, total: 216 ms Wall time: 1h 1s
You might have created results with a library that’s hard to install and therefore you have only managed to install it on one very old computer in the basement, so you probably cannot run this whenever you build your Sphinx docs.
from a_very_rare_library import calculate_the_answer
If an exception is raised during the Sphinx build process, it is stopped (the build process, not the exception!). If you want to show to your audience how an exception looks like, you have two choices:
Execute the notebook beforehand and save the results, like it’s done in this example notebook:
1 / 0
--------------------------------------------------------------------------- ZeroDivisionError Traceback (most recent call last) <ipython-input-5-b710d87c980c> in <module>() ----> 1 1 / 0 ZeroDivisionError: division by zero
nbsphinx executes notebooks, it uses the
nbconvert module to do so. Certain Jupyter clients might produce output that differs from what
nbconvert would produce. To preserve those original outputs, the notebook has to be executed and saved before running Sphinx.
For example, the JupyterLab help system shows the help text as cell outputs, while executing with
nbconvert doesn’t produce any output.
Signature: sorted(iterable, /, *, key=None, reverse=False) Docstring: Return a new list containing all items from the iterable in ascending order. A custom key function can be supplied to customize the sort order, and the reverse flag can be set to request the result in descending order. Type: builtin_function_or_method
If your code asks for user input, it probably doesn’t work when executed by Sphinx/
nbsphinx. You’ll probably get an error like this:
StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.
In this case, you can run the notebook interactively, provide the desired inputs and then save the notebook including its cell outputs.
name = input('What... is your name?') quest = input('What... is your quest?') color = input('What... is your favorite color?')
What... is your name? Sir Lancelot of Camelot What... is your quest? To seek the Holy Grail What... is your favorite color? Blue