Executing pages of your book
✨experimental✨
Sometimes you'd like to execute each page's content before building its HTML - thisensures that the outputs are up-to-date and that they still run. Jupyter Bookhas the ability to execute any code in your content when you build each page's HTML although by default this is disabled for notebook and simple markdown documents.
Default execution behavior
Jupyter Book will decide whether to execute your book's content based on the types of files used to store your content. By default, Jupyter Book assumes that :
- notebook outputs are already present in an
.ipynb
file, and consequently any Jupyter Notebooks (.ipynb
documents), will not be executed; (see below for how to change this behavior); - simple raw markdown files (
.md
, no Jupytext header) will also not be executed: Jupyter Book assumes that any code blocks were meant for viewing only, not running; - any Jupytext documents (currently,
.py
,.md
, or.Rmd
files that have jupytext YAML front-matter content) will be executed when the page's HTML is built. There are a few ways to alter this behavior in order to execute your book content at build time using several convenience functions and options which we'll cover below.
Run a single page in-place: jupyter-book run
Jupyter Book provides a convenience command-line function that executesone or more Jupyter Notebooks and stores the outputs inline within the same ipynb
file. This provides a straightforward way of ensuring that source notebook files contain freshly computed cell outputs when you create your Jupyter Book.
This jupyter-book run
command-line function can be called with the path to a singlebook page like so:
jupyter-book run path/to/notebook.ipynb
It will simply execute the notebook and insert the code cell outputs in-place.
You can also specify a folder with a collection of pages as the first argument:
jupyter-book run path/to/notebook_folder
In this case, all notebooks in this folder and sub-folders will be run in-place.
Run all your book's content when building: jupyter-book build —execute
If you'd like to run each page of your book (where possible) when building theHTML for your book pages without modifying the original source document, use the —execute
flag when building each page's HTML:
jupyter-book build —execute
This will cause each .ipynb
and jupytext-formatted page to be executed when it is built.In this case, the source content files will not be modified, but the code execution outputs will be placed in each page's HTML.
Remember that the HTML for each page is cached until you update your content. Thefirst time you run jupyter-book build —execute
, each page of your book will be runand converted to HTML which may take some time. However, after the first run, only the pages that have been updated will be executed and converted to HTML, which should lead to subsequently faster build times as you update your content.
Here's a quick summary of this behavior:
Type | jupyter run | jupyter-book build | jupyter-book build —execute |
---|---|---|---|
Jupyter Notebooks (.ipynb ) | Code executes; fresh outputs inserted inline in source notebook | Code doesn't execute; outstanding outputs displayed inline in HTML | Code executes; fresh outputs displayed inline in HTML |
Raw markdown (.md ) | Code doesn't execute | Code doesn't execute; generated code outputs not supported in raw markdown documents | Code doesn't execute; generated code outputs not available for HTML |
Jupytext pages (.md , .Rmd , .py ) | Code outputs not supported in Jupytext documents | Code executes; fresh outputs displayed inline in HTML | Code executes; fresh outputs displayed inline in HTML |
This page was created by The Jupyter Book Community