Jupyter Notebooks

Jupyter Notebooks#

此笔记本展示了使用 MyST 解析器将 Jupyter 笔记本直接解析到 Sphinx 中的过程。[1]

Markdown#

参见

有关您可以使用 MyST Markdown 编写的内容的更多信息，请参阅 MyST 解析器文档。

配置#

MyST-NB 解析器源自 基础 MyST 解析器，因此所有相同的配置选项都可用。有关完整选项集，请参阅 MyST 配置选项，有关所有语法选项，请参阅 MyST 语法指南。

要从此笔记本构建文档，设置了以下选项：

myst_enable_extensions = [
    "amsmath",
    "colon_fence",
    "deflist",
    "dollarmath",
    "html_image",
]
myst_url_schemes = ("http", "https", "mailto")

备注

加载 myst_nb 扩展还会激活 myst_parser 扩展，以启用 MyST 风格的 Markdown。不需要在 extensions 列表中显式添加此扩展。

语法#

如您所见，Markdown 按预期解析。嵌入图像应按预期工作。例如，这是 MyST-NB 徽标：

![myst-nb logo](../_static/logo-wide.svg)

myst-nb logo

通过将 "html_image" 添加到 sphinx 配置中的 myst_enable_extensions 列表（参见此处），您甚至可以添加带有属性的 HTML img 标签：

<img src="../_static/logo-wide.svg" alt="logo" width="200px" class="shadow mb-2">
logo

由于 MyST-NB 使用 MyST-markdown 解析器，您可以在笔记本中包含带有 Sphinx 的丰富 Markdown。例如，这是注释警告块：

备注

Wow, a note! It was generated with this code (as explained here):

:::{note}
**Wow**, a note!
:::

如果您希望使用‘裸’LaTeX 方程，则应将 "amsmath" 添加到 sphinx 配置中的 myst_enable_extensions 列表中。这在 此处 有解释，并且如下工作：

\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*}\]

还可以在笔记本中使用方程编号和引用等功能：

$$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.

您可以在 MyST 文档 中查看此示例使用的语法。

代码单元和输出#

可以运行单元，单元输出将被捕获并插入到生成的 Sphinx 站点中。

__repr__ 和 HTML 输出#

例如，这是一些简单的 Python 代码：

import matplotlib.pyplot as plt
import numpy as np
data = np.random.rand(3, 100) * 100
data[:, :10]

array([[46.86612815, 62.60697049, 85.59189247, 87.46606922, 75.54000797,
         6.62183604, 39.50907777, 84.33016888, 91.34053874, 79.19356346],
       [64.77593952, 96.13895596,  2.48227103, 54.5865616 , 23.08410447,
        69.32429056, 47.66232733, 48.98152818, 33.44277228, 29.25828781],
       [75.00241712, 14.931024  , 57.85136589, 17.39564049, 96.62533914,
        57.92169706,  2.64429326, 14.25516463, 83.10306787, 44.97071672]])

这也适用于 HTML 输出

import pandas as pd
df = pd.DataFrame(data.T, columns=['a', 'b', 'c'])
df.head()
a b c
0 46.866128 64.775940 75.002417
1 62.606970 96.138956 14.931024
2 85.591892 2.482271 57.851366
3 87.466069 54.586562 17.395640
4 75.540008 23.084104 96.625339

以及数学输出

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}\]

这也适用于错误消息：

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

图像#

从代码生成的图像（例如，使用 Matplotlib）也将被嵌入。

fig, ax = plt.subplots()
ax.scatter(*data, c=data[2])

<matplotlib.collections.PathCollection at 0x7fcd5ff0fb00>
../_images/87f25888973201eb42c2a38446b2485251c35cbf1e97161bcf0849ce241bb6fb.png

原始单元#

原始单元类型 可用于将内容专门渲染为特定的 MIME 媒体类型。

```{raw-cell}
:format: text/html

<p>My cat is <strong>very</strong> grumpy.</p>
```

My cat is very grumpy.