Migrating to jupyter-book>=0.14
#
This release of jupyter-book>=0.14
includes major updates to myst-nb
and myst-parser that include some breaking changes.
This update includes incorporating three major updates to myst-nb moving from myst-nb~=0.13.1
to myst-nb~=0.17.1
which incorporates changes to the underlying myst-parser moving from myst-parser~=0.15
to myst-parser~=0.18
.
While every effort has been made to enable backward compatibility, there are some new warnings that may appear when upgrading to the latest version. This page has been put together to help explain these warnings and provides suggestions on how to fix them.
The latest configuration options are well documented in the underlying libraries:
so it is worth referring to these resources when updating any options or using more advacned features in your project.
Common Configuration Updates#
A number of configuration option names have been updated.
Some of the more commonly used options include those that control execution of jupyter
notebooks.
The majority of options concerning notebooks have an nb_
prefix added to the pre-existing option name,
however there are some cases where the option name has been changed.
For example jupyter_execute_notebooks
has become nb_execution_mode
. Most of the old option
names will be auto-converted and a warning is issued by myst-nb such as:
WARNING: 'jupyter_execute_notebooks' is deprecated for 'nb_execution_mode' [mystnb.config]
These warning messages now includes the software that is responsible as seen in the square brackets. This helps to identify where your warning is coming from and using the myst-nb documentation may be a good source of information.
Below we highlight some of the configuration changes here, which we found useful when updating our range projects. It should be noted that these are only a handful of examples, please refer to the doc links mentioned above raise an issue.
Book level configuration#
Some of the configurations have been renamed, and the variable types of some have also been changed.
The noteworthy configuration changes which effected most of our projects were:
jupyter_execute_notebooks
is renamed tonb_execution_mode
.nb_render_priority
is renamed tonb_mime_priority_overrides
and it accepts a sequence of tuples. Each tuple takes three mandatory entries namelybuilder name
,mime type
, andpriority
.
An Example:
sphinx:
config:
nb_render_priority:
- "application/vnd.jupyter.widget-view+json"
- "application/javascript"
- "text/html"
- "text/latex"
- "image/svg+xml"
- "image/png"
- "image/jpeg"
- "text/markdown"
- "text/plain"
would become:
sphinx:
config:
nb_mime_priority_overrides: [
['html', 'application/vnd.jupyter.widget-view+json', 10],
['html', 'application/javascript', 20],
['html', 'text/html', 30],
['html', 'text/latex', 40],
['html', 'image/svg+xml', 50],
['html', 'image/png', 60],
['html', 'image/jpeg', 70],
['html', 'text/markdown', 80],
['html', 'text/plain', 90],
]
There are additional option name changes that should be notified to you via the warnings
output.
Configuration pass-through (file level)#
If you wish to specify a configuration options that is processed by myst-nb,
overriding the default configuration now requires them to under the mystnb
key. Likewise, if a configuration option is
processed by myst-parser, then they should be under the myst
key.
Some examples follow:
myst-nb#
To set the execution_timeout
config option managed by mystnb
you would specify the following:
```
---
file_format: mystnb
mystnb:
execution_timeout: 60
---
```
in the header of the notebook (or page).
Myst-parser#
To make document level variables that will be resolved by myst-parser
then this configuration can be specified under the myst
key in the configuration for each notebook (or page) such as:
```
---
myst:
substitutions:
key1: "I'm a **substitution**"
key2: |
```{note}
{{ key1 }}
```
fishy: |
```{image} /images/fun-fish.png
:alt: fishy
:width: 200px
```
jinja: "[Jinja templates](https://jinja.palletsprojects.com/en/2.11.x/)"
repo_name: "jupyter-book"
repo_url: "[my repo url](https://github.com/executablebooks/jupyter-book)"
---
```
Configuration pass-through (cell level)#
Similarly, overriding the default configuration can also be done at the cell level
and requires them to be under the mystnb
key.
Since cell-level operations are in myst-nb domain, we don’t have to worry about Myst-parser here.
This changes the way configuration was previously captured under the render
title, replacing it with mystnb
.
An example of the new configuration:
```{code-cell} ipython3
---
mystnb:
image:
width: 200px
alt: fun-fish
classes: shadow bg-primary
figure:
caption: |
Hey everyone its **party** time!
name: fun-fish
---
from IPython.display import Image
Image("../images/fun-fish.png")
```
Changes to glue
#
Tip
One of the key changes is that glue
directives will now need to use :doc:
to
reference objects that are created in a separate notebook (page or document).
The glue
behaviour is the same as previously within the same notebook (page or document)
The glue
roles and directives will only identify keys in the same notebook, by default.
To reference a glue object in another notebook (page or document), now requires you to use a :doc:
key,
which specifies the relative path to the notebook.
An example:
```{glue} cool_text
:doc: /content/executable/output-insert.md
```
will render as
'here is some text!'
Tip
The file extension
of the document needs to be specified. So you need to use
executable/output-insert.md
rather than executable/output-insert
as can be the case
in some other sphinx/docutils
directives
DataFrames:
first | second | third | |
---|---|---|---|
0 | 2.925578 | 3.106738 | 3.017738 |
1 | 3.359972 | 3.127909 | 2.729874 |
2 | 3.145868 | 2.721771 | 3.076413 |
3 | 3.294150 | 2.619426 | 3.075810 |
4 | 3.582161 | 3.337726 | 3.184996 |
Limitations for Figures and Math#
There are currently some limitations based on the mime
types for Figures
and Math
.
Math:
Using the glue
directive between documents for math results in a text representation:
(sqrt(5)*I)**\alpha*(1/2 - 2*sqrt(5)*I/5) + (-sqrt(5)*I)**\alpha*(1/2 + 2*sqrt(5)*I/5)
Figures:
The resultant text representation when using the glue
directive is similar for figures.
For example, if you glue in the figure sorted_means_fig
from the executable/output-insert.md
document:
```{glue} sorted_means_fig
:doc: /content/executable/output-insert.md
```
it will be rendered as:
<Figure size 600x200 with 1 Axes>
which is the text description of the image.
These issues have been reported to the myst-nb team.