A Pre-Executed Notebook

Notebooks with no outputs are automatically executed during the Sphinx build process. If, however, there is at least one output cell present, the notebook is not evaluated and included as is.

Explicitly disabling notebook execution

If you want to include a notebook without outputs and yet don’t want nbsphinx to execute it for you, you can explicitly disable this feature setting the nbsphinx_execute config option to "false". nbsphinx_execute has three possible states, "always", "auto" (default), and "never".

You can do this globally by setting this option in conf.py:

nbsphinx_execute = 'never'

Or on a per notebook basis by adding this to the notebook’s JSON metadata:

"nbsphinx": {
  "execute": "never"
},

This can be useful for the following use cases.

Long-Running Cells

If you are doing some very time-consuming computations, you may go over the default timeout for a cell, which is 30 seconds. To include long-running cells, you have two choices:

  1. Change the timeout for a cell either generally or on a per-notebook basis – see Long-Running Cells.
  2. Execute the notebook beforehand and save the results, like it’s done in this example notebook:
In [1]:
import time
In [2]:
%time time.sleep(60 * 60)
6 * 7
CPU times: user 160 ms, sys: 56 ms, total: 216 ms
Wall time: 1h 1s
Out[2]:
42

Rare Libraries

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.

In [3]:
from a_very_rare_library import calculate_the_answer
In [4]:
calculate_the_answer()
Out[4]:
42

Exceptions

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:

  1. Allow errors – either generally or on a per-notebook basis – see Ignoring Errors.
  2. Execute the notebook beforehand and save the results, like it’s done in this example notebook:
In [5]:
1 / 0
---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
<ipython-input-5-b710d87c980c> in <module>()
----> 1 1 / 0

ZeroDivisionError: division by zero