jupytext | kernelspec | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
This notebook is a demonstration of directly-parsing Jupyter Notebooks into Sphinx using the MyST parser.[^download]
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")
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)
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*}
\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 {math:numref}euler
, was elected one of the
most beautiful mathematical formulas.
You can see the syntax used for this example here in the MyST documentation.
You can run cells, and the cell outputs will be captured and inserted into the resulting Sphinx site.
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]
This will also work with HTML outputs
import pandas as pd
df = pd.DataFrame(data.T, columns=['a', 'b', 'c'])
df.head()
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:
:tags: [raises-exception]
print("This will be properly printed...")
print(thiswont)
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])
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"
}