Execute and cache your pages¶
Jupyter Book can automatically run and cache any notebook pages. Notebooks can either be run each time the documentation is built, or cached locally so that notebooks will only be re-run when the code cells in a notebook have changed.
Cacheing behavior is controlled with the execute:
section
in your _config.yml
file. See
the sections below for each configuration option and its effect.
Tip
If you’d like to execute code that is in your markdown files, you can use the
{code-cell}
directive in MyST markdown. See Notebooks written entirely in markdown
for more information.
Trigger notebook execution¶
By default, Jupyter Book will execute any content files that have a notebook structure, and that are missing at least one output. This is equivalent to the following configuration in _config.yml`:
execute:
execute_notebooks: auto
This will only execute notebooks that are missing at least one output. If the notebook has all of its outputs populated, then it will not be executed.
To force the execution of all notebooks, regardless of their outputs, change the above configuration value to:
execute_notebooks: force
To cache execution outputs with jupyter-cache, change the above configuration value to:
execute:
execute_notebooks: cache
See Cacheing the notebook execution for more information.
To turn off notebook execution,change the above configuration value to:
execute:
execute_notebooks: 'off'
Exclude files from execution¶
To exclude certain file patterns from execution, use the following configuration:
execute:
exclude_patterns:
- 'pattern1'
- 'pattern2'
- '*pattern3withwildcard'
Any file that matches one of the items in exclude_patterns
will not be
executed.
Cacheing the notebook execution¶
You may also cache the results of executing a notebook page using jupyter-cache. In
this case, when a page is executed, its outputs will be stored in a local database.
This allows you to be sure that the outputs in your documentation are up-to-date,
while saving time avoiding unnecessary re-execution. It also allows you to store your
.ipynb
files in your git
repository without their outputs, but still leverage
a cache to save time when building your site.
When you re-build your site, the following will happen:
Notebooks that have not seen changes to their code cells since the last build will not be re-executed. Instead, their outputs will be pulled from the cache and inserted into your site.
Notebooks that have any change to their code cells will be re-executed, and the cache will be updated with the new outputs.
To enable cacheing of notebook outputs, use the following configuration:
execute:
execute_notebooks: cache
By default, the cache will be placed in the parent of your build folder. Generally,
this is in _build/.jupyter_cache
.
You may also specify a path to the location of a jupyter cache you’d like to use:
execute:
cache: path/to/mycache
The path should point to an empty folder, or a folder where a jupyter cache already exists.
Execution FAQs¶
How does execution deal with relative paths in my code?¶
The behavior of relative paths in your code is slightly different depending on
whether you’re executing with auto
or with cache
.
If executing with
auto
notebooks will execute in the folder where they exist and relative paths will work.If executing with
cache
then the notebook will execute in a temporary folder, and relative paths will not work. Support for relative paths is planned for the future.
How can I include code that raises errors?¶
In some cases, you may want to intentionally show code that doesn’t work (e.g., to show
the error message). To do this, add a raises-exception
tag to your code cell. This
can be done via a Jupyter interface, or via the {code-cell}
directive like so:
```{code-cell}
---
tags: [raises-exception]
---
print(thisvariabledoesntexist)
```
Which produces:
print(thisvariabledoesntexist)
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-1-125c53ec1b82> in <module>
----> 1 print(thisvariabledoesntexist)
NameError: name 'thisvariabledoesntexist' is not defined