An example Jupyter Notebook#
This notebook is a demonstration of directly-parsing Jupyter Notebooks into Sphinx using the MyST parser.[^download]
Markdown#
Configuration#
https://myst-parser.readthedocs.io/en/latest/using/intro.html#getting-started
To build documentation from this notebook, the following options are set:
myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"html_image",
]
myst_url_schemes = ("http", "https", "mailto")
Syntax#
As you can see, markdown is parsed as expected. Embedding images should work as expected. For example, here’s the 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="../img/unitary_fund_logo.png" 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:
Note
Wow, a note! It was generated with this code (as explained here):
:::{note}
**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:
\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)
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([[96.33715155, 36.200233 , 83.17308466, 68.26178074, 46.18793313,
23.12945 , 24.41389046, 29.42126059, 5.49089622, 73.84335662],
[67.66519549, 84.89097832, 39.05727936, 90.06243558, 55.89425126,
80.8049608 , 3.28922145, 14.78776169, 16.44944353, 10.44046724],
[ 7.30319043, 70.90110657, 99.81211384, 90.55839172, 71.62617594,
38.72428369, 33.8185647 , 23.82872642, 42.46759169, 50.35609837]])
This will also work with HTML outputs
import pandas as pd
df = pd.DataFrame(data.T, columns=['a', 'b', 'c'])
df.head()
a | b | c | |
---|---|---|---|
0 | 96.337152 | 67.665195 | 7.303190 |
1 | 36.200233 | 84.890978 | 70.901107 |
2 | 83.173085 | 39.057279 | 99.812114 |
3 | 68.261781 | 90.062436 | 90.558392 |
4 | 46.187933 | 55.894251 | 71.626176 |
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}")
This works for error messages as well:
print("This will be properly printed...")
print(thiswont)
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#
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 0x7f4c8047c850>

Thumbnail for the Notebook#
To add a thumbnail for an example notebook, first add the thumbnail image file to docs/source/_thumbnails
. Next, modify the docs/source/conf.py
to include the example and thumbnail in the nbsphinx_thumbnails dictionary at the end of the file. The sample below contains both a generic template and an actual example.
nbsphinx_thumbnails = {
"examples/{EXAMPLE_FILENAME_WITHOUT_.md}": "_static/{THUMBNAIL_FILENAME_WITH_EXTENSION}",
"examples/hamiltonians": "_static/vqe-cirq-pauli-sum-mitigation-plot.png"
}