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:

![myst-nb logo](../img/unitary_fund_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_fund_logo.png" alt="logo" width="200px" class="shadow mb-2">
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 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([[15.76551102,  4.1493035 , 25.35873893, 60.58047014, 44.74308891,
        46.53700937, 67.97296761, 46.08392462, 99.30668489, 65.6628961 ],
       [77.81081818, 36.56472508, 66.6553391 , 66.82866891,  9.96169767,
        46.1281158 , 51.68394127, 47.18632496, 21.44839956, 71.86699423],
       [28.24272962, 50.7723101 , 64.67703796, 84.85663079, 45.12973011,
        63.18740345,  9.81709706, 88.86056304, 15.38285761,  9.68160979]])

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 15.765511 77.810818 28.242730
1 4.149303 36.564725 50.772310
2 25.358739 66.655339 64.677038
3 60.580470 66.828669 84.856631
4 44.743089 9.961698 45.129730

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)
/tmp/ipykernel_497/3073679017.py 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 0x7f5ff87cec90>
../_images/template_9_1.png

Testing

The following cells setup a test (which won’t be rendered in the notebook), the test code and the test output cell:

SIMULATOR = DensityMatrixSimulator()
# 0.1% depolarizing noise
qbit = LineQubit(0)
circ = Circuit(X(qbit) for _ in range(80))

def simulate_with_noise(circ: Circuit) -> float:
   circuit = circ.with_noise(depolarize(p=0.001))
   rho = SIMULATOR.simulate(circuit).final_density_matrix
   # define the computational basis observable
   obs = np.diag([1, 0])
   expectation = np.real(np.trace(rho @ obs))
   return expectation

unmitigated = simulate_with_noise(circ)
exact = 1
print(f"Error in simulation is {exact - unmitigated:.{3}}")

Error in simulation is 0.0506
Contributing to the Documentation Mitiq Git flow