An example Jupyter Notebook¶

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

Markdown¶

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

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 block:

Note

Wow, a note! It was generated with this code:

```{note}
Wow, a note!
```

Equations work as expected:

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

And some MyST-specific features like equation numbering can be used in notebooks:

(1)¶\[e^{i\pi} + 1 = 0\]

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

You can see the syntax used for this example here.

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]

Matplotlib is building the font cache; this may take a moment.

array([[ 7.65856217, 77.50683455, 76.6292053 , 75.50042516,  9.53204748,
        20.57801603, 78.64515099, 71.24094754, 35.09063661, 78.64697143],
       [81.67000198, 15.85152669, 35.30333755,  5.43947639, 44.94160698,
        90.28811921, 82.06552136, 47.91661398, 19.41788208,  2.98159657],
       [44.36282524, 34.64668099, 22.23518987, 49.44878042, 66.11661212,
        15.05490797, 71.07759266,  8.03645309, 63.13802588, 73.9903403 ]])

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	7.658562	81.670002	44.362825
1	77.506835	15.851527	34.646681
2	76.629205	35.303338	22.235190
3	75.500425	5.439476	49.448780
4	9.532047	44.941607	66.116612

as well as math outputs

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

\[\displaystyle \sum_{i=0}^n i^2 = rac{(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)
<ipython-input-4-8f5b3a77886c> in <module>
      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 0x7f89d9970160>

1: This notebook can be downloaded as basic.ipynb and basic.md