Jupyter Notebooks#

This notebook is a demonstration of directly-parsing Jupyter Notebooks into Sphinx using the MyST parser.[1]


See also

For more information about what you can write with MyST Markdown, see the MyST Parser documentation.


The MyST-NB parser derives from the base MyST-Parser, and so all the same configuration options are available. See the MyST configuration options for the full set of options, and MyST syntax guide for all the syntax options.

To build documentation from this notebook, the following options are set:

myst_enable_extensions = [
myst_url_schemes = ("http", "https", "mailto")


Loading the myst_nb extension also activates the myst_parser extension, for enabling the MyST flavour of Markdown. It is not required to add this explicitly in the list of extensions.


As you can see, markdown is parsed as expected. Embedding images should work as expected. For example, here’s the MyST-NB logo:

![myst-nb logo](../_static/logo-wide.svg)

myst-nb logo

By adding "html_image" to the myst_enable_extensions list in the sphinx configuration (see here), you can even add HTML img tags with attributes:

<img src="../_static/logo-wide.svg" alt="logo" width="200px" class="shadow mb-2">

Because MyST-NB is using the MyST-markdown parser, you can include rich markdown with Sphinx in your notebook. For example, here’s a note admonition block:


Wow, a note! It was generated with this code (as explained here):

**Wow**, a note!

If you wish to use “bare” LaTeX equations, then you should add "amsmath" to the myst_enable_extensions list in the sphinx configuration. This is explained here, and works as such:

\frac {\partial u}{\partial x} + \frac{\partial v}{\partial y} = - \, \frac{\partial w}{\partial z}

2x - 5y &=  8 \\
3x + 9y &=  -12
(1)#\[\begin{equation} \frac {\partial u}{\partial x} + \frac{\partial v}{\partial y} = - \, \frac{\partial w}{\partial z} \end{equation}\]
\[\begin{align*} 2x - 5y &= 8 \\ 3x + 9y &= -12 \end{align*}\]

Also you can use features like equation numbering and referencing in the notebooks:

$$e^{i\pi} + 1 = 0$$ (euler)
(2)#\[e^{i\pi} + 1 = 0\]

Euler’s identity, equation (2), was elected one of the most beautiful mathematical formulas.

You can see the syntax used for this example here in the MyST documentation.

Code cells and outputs#

You can run cells, and the cell outputs will be captured and inserted into the resulting Sphinx site.

__repr__ and HTML outputs#

For example, here’s some simple Python:

import matplotlib.pyplot as plt
import numpy as np
data = np.random.rand(3, 100) * 100
data[:, :10]
array([[54.09463179, 51.46346266, 67.87525829, 55.48706729,  6.6748211 ,
        69.42579785, 63.68020391, 94.0680362 , 47.64956536,  8.06736802],
       [60.84560633, 34.24202916, 89.30422372, 65.97694579, 64.798404  ,
        30.91727744,  7.25617705, 85.17568709, 94.10283787,  5.03862812],
       [92.65620548, 98.52057044, 63.12212377, 61.56379955, 32.35329173,
        74.14039818,  8.04116117, 84.23433543, 47.03392572, 54.76472841]])

This will also work with HTML outputs

import pandas as pd
df = pd.DataFrame(data.T, columns=['a', 'b', 'c'])
a b c
0 54.094632 60.845606 92.656205
1 51.463463 34.242029 98.520570
2 67.875258 89.304224 63.122124
3 55.487067 65.976946 61.563800
4 6.674821 64.798404 32.353292

as well as math outputs

from IPython.display import Math
Math(r"\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}")
\[\displaystyle \sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}\]

This works for error messages as well:

print("This will be properly printed...")
This will be properly printed...
NameError                                 Traceback (most recent call last)
Cell In[4], line 2
      1 print("This will be properly printed...")
----> 2 print(thiswont)

NameError: name 'thiswont' is not defined


Images that are generated from your code (e.g., with Matplotlib) will also be embedded.

fig, ax = plt.subplots()
ax.scatter(*data, c=data[2])
<matplotlib.collections.PathCollection at 0x7fa4090d3690>

Raw cells#

The raw cell type can be used to specifically render the content as a specific MIME media type.

:format: text/html

<p>My cat is <strong>very</strong> grumpy.</p>

My cat is very grumpy.