Shortcuts

This page was generated from doc/pre-executed.ipynb. Interactive online version: Binder badge

Pre-Executing Notebooks

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.

Long-Running Cells

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.

[1]:
import time
[2]:
%time time.sleep(60 * 60)
6 * 7
CPU times: user 160 ms, sys: 56 ms, total: 216 ms
Wall time: 1h 1s
[2]:
42

If you do want to execute your notebooks, but some cells run for a long time, you can change the timeout, see Cell Execution Timeout.

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.

[3]:
from a_very_rare_library import calculate_the_answer
[4]:
calculate_the_answer()
[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 or per-cell basis – see Ignoring Errors (per cell).

  2. Execute the notebook beforehand and save the results, like it’s done in this example notebook:

[5]:
1 / 0
---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
<ipython-input-5-b710d87c980c> in <module>()
----> 1 1 / 0

ZeroDivisionError: division by zero

Client-specific Outputs

When 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.

[6]:
sorted?
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

Read the Docs v: pytorch-theme
Versions
latest
0.5.0
0.4.3
0.4.2
0.4.1
0.3.5
0.3.4
0.3.3
0.3.2
0.3.1
0.3.0
0.2.18
0.2.17
0.2.16
0.2.15
0.2.14
0.2.13
0.2.12
0.2.11
0.2.10
0.2.9
0.2.8
0.2.7
0.2.6
0.2.5
0.2.4
0.2.3
0.2.2
0.2.1
0.2.0
typlog-theme
traditional-theme
sphinxdoc-theme
sizzle-theme
scrolls-theme
rtd-theme
pyviz-theme
pytorch-theme
pyramid-theme
py3doc-enhanced-theme
press-theme
pangeo-theme
pandas-theme
nature-theme
material-theme
maisie-theme
jupyter-theme
julia-theme
haiku-theme
guzzle-theme
cloud-theme
classic-theme
bootstrap-theme
bizstyle-theme
better-theme
basicstrap-theme
astropy-theme
alabaster-theme
alabaster-jupyterhub-theme
agogo-theme
0.1.0
Downloads
pdf
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.

Docs

Lorem ipsum dolor sit amet, consectetur

View Docs

Tutorials

Lorem ipsum dolor sit amet, consectetur

View Tutorials

Resources

Lorem ipsum dolor sit amet, consectetur

View Resources