Jupyter Notebook 支持¶

Jupyter notebooks 可以作为文档构建系统的一部分进行渲染，以替代 markdown 文件。文档站点使用 mkdocs-jupyter 来构建和渲染 jupyter notebooks 为 markdown 文件。

注意：jupyter 渲染有一些限制。

1. Notebooks 不会作为文档发布流程的一部分执行。CI 测试会单独运行，以确保 notebook 的一致性（请参阅 测试 Jupyter Notebook）。
2. Notebook markdown 单元格不支持全方位的 mkdocs-material 配置，包括诸如提示框、通过 mkdocstrings 等引用自动生成的 API 文档等（更多信息请参阅 此处）。

代码示例¶

Markdown 标题可用于创建 TOC，类似于传统的 mkdocs 页面。

In [1]

a = 1
b = 2
a + b

a = 1 b = 2 a + b

Out[1]

3

嵌入式可视化¶

我们还可以使用标准方法在 notebook 中嵌入图像。

In [2]

%matplotlib inline
import matplotlib.pyplot as plt
import numpy as np

xs = np.linspace(0, 2*np.pi, 100)
plt.plot(xs, np.sin(xs))

%matplotlib inline import matplotlib.pyplot as plt import numpy as np xs = np.linspace(0, 2*np.pi, 100) plt.plot(xs, np.sin(xs))

Out[2]

[<matplotlib.lines.Line2D at 0x79f258429570>]

测试 Jupyter Notebook¶

Jupyter notebooks 作为 CI 构建套件的一部分使用 nbval 运行。要本地运行这些测试，请从存储库根目录运行

pytest --nbval-lax docs/

。默认情况下，nbval 将仅检查 notebook 是否成功执行。要添加其他检查以确保输出的一致性，请添加 #NBVAL_CHECK_OUTPUT 标记注释，这将确保保存的 jupyter notebook 的输出与在 CI 中执行 notebook 时的输出匹配。

例如

In [3]

#NBVAL_CHECK_OUTPUT
# pragma: allowlist secret

import torch
print(torch.__version__)

#NBVAL_CHECK_OUTPUT # pragma: allowlist secret import torch print(torch.__version__)

2.3.0a0+ebedce2