An example Jupyter Notebook#

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

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:

![myst-nb logo](../img/unitary_foundation_logo.png)

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_foundation_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*}

(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([[5.58082415e+01, 8.22638847e+01, 9.43253663e+00, 6.54624237e+01,
        8.79443957e+01, 2.66703148e+01, 7.47246631e-01, 5.72684682e+01,
        4.43792246e+01, 1.30168127e-02],
       [7.51976450e+01, 9.23064908e+01, 3.52885197e+01, 1.23420491e+01,
        2.38105648e+01, 1.30822536e+01, 2.49715899e+01, 1.37689030e+01,
        8.41292711e+01, 6.49356864e+01],
       [8.32953665e+01, 5.84274817e+01, 6.18181079e+01, 2.94427200e+01,
        4.36002585e+01, 1.34470176e+01, 3.71239711e+01, 6.16380807e+01,
        7.50905992e+01, 6.60797919e+01]])

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	55.808242	75.197645	83.295366
1	82.263885	92.306491	58.427482
2	9.432537	35.288520	61.818108
3	65.462424	12.342049	29.442720
4	87.944396	23.810565	43.600258

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...")
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 0x716a84cf4230>

../_images/adb41124dc2735994c7bba59f539965d41284660f58f90c6a3d9af5115eae09d.png

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"
    }