执行并缓存您的页面

执行并缓存您的页面#

Jupyter Book 可以自动运行并缓存任何笔记本页面。笔记本可以在每次构建文档时运行，或者在本地缓存，以便只有在笔记本的代码单元发生变化时才会重新运行笔记本。

缓存行为由 execute: 部分在您的 _config.yml 文件中控制。参见以下各配置选项及其效果的章节。

Tip

如果您希望执行 Markdown 文件中的代码，您可以使用 MyST Markdown 中的 {code-cell} 指令。有关更多信息，请参见完全用 Markdown 编写的笔记本。

触发笔记本执行#

默认情况下，Jupyter Book 将执行任何具有笔记本结构且缺少至少一个输出的内容文件。这相当于在 _config.yml 中的以下配置：

execute:
  execute_notebooks: auto

或等效地：

sphinx:
  config:
    nb_execution_mode: auto

上述两种配置都是全局的，对于每文件使用 execution_mode 键。

这将仅执行缺少至少一个输出的笔记本。如果笔记本的所有输出都已填充，则不会执行。

要强制执行所有笔记本，无论其输出如何，请将上述配置值更改为：

execute:
  execute_notebooks: force

要使用 jupyter-cache 缓存执行输出，请将上述配置值更改为：

execute:
  execute_notebooks: cache

参见缓存笔记本执行了解更多信息。

要在解析期间内联执行笔记本，请将上述配置值更改为：

execute:
  execute_notebooks: inline

参见内联变量评估（eval）了解更多信息。

要关闭笔记本执行，请将上述配置值更改为：

execute:
  execute_notebooks: 'off'

从执行中排除文件#

要排除某些文件模式从执行，请使用以下配置：

execute:
  exclude_patterns:
    - 'pattern1'
    - 'pattern2'
    - '*pattern3withwildcard'

任何与 exclude_patterns 中的项目匹配的文件将不会被执行。

Tip

要自动排除所有不在目录中的文件，请参见禁用构建不在目录中的文件

缓存笔记本执行#

您还可以使用 jupyter-cache 缓存执行笔记本页面的结果。在这种情况下，当页面被执行时，其输出将存储在本地数据库中。这使您可以确保文档中的输出是最新的，同时节省时间避免不必要的重新执行。它还允许您将 .ipynb 文件存储在 git 仓库中 而不包含其输出，但仍可以利用缓存来节省构建站点的时间。

当您重新构建站点时，将发生以下情况：

自上次构建以来代码单元未发生变化的笔记本将不会重新执行。相反，其输出将从缓存中提取并插入到您的站点中。
代码单元有任何更改的笔记本将被重新执行，并且缓存将更新为新的输出。

要启用笔记本输出的缓存，请使用以下配置：

execute:
  execute_notebooks: cache

默认情况下，缓存将放置在构建文件夹的父目录中。通常，它位于 _build/.jupyter_cache 中。

您还可以指定要使用的 jupyter 缓存的路径：

execute:
  cache: path/to/mycache

路径应指向一个空文件夹，或一个已存在 jupyter 缓存的文件夹。

执行配置#

您可以使用 _config.yml 在项目级别控制笔记本执行以及输出内容的处理方式，但在某些情况下，也可以在笔记本和代码单元级别进行控制。以下我们探讨了几种实现这一点的方法。

执行工作目录#

Important

cache 的默认行为现在是在本地目录中运行。这是从 v0.7 版本以来的变化。

默认情况下，笔记本运行的命令工作目录（cwd）将是其所在的目录（对于 auto 和 cache）。这意味着需要访问相对路径中的资产的笔记本将正常工作。

或者，如果您希望在临时文件夹中隔离笔记本执行，您可以使用以下 _config.yml 设置：

execute:
  在临时目录中运行: true

设置执行超时#

执行超时定义了每个笔记本单元格允许运行的最长时间（以秒为单位）。如果执行时间超过设定值，则会引发异常。默认值为30秒，因此对于长时间运行的单元格，您可能需要指定更高的值。超时选项也可以设置为-1，以移除任何执行时间的限制。

您可以在 _config.yml 中为所有笔记本执行设置超时：

execute:
  timeout: 100

该全局值也可以通过在笔记本元数据中添加以下内容来为每个笔记本覆盖：

{
 "metadata": {
  "execution": {
      "timeout": 30
  }
}

处理引发错误的代码#

在某些情况下，您可能希望有意展示无法正常工作的代码（例如，展示错误信息）。

您可以在 _config.yml 中允许所有笔记本的错误：

execute:
  allow_errors: true

该全局值也可以通过在笔记本元数据中添加以下内容来为每个笔记本覆盖：

{
 "metadata": {
  "execution": {
      "allow_errors": false
  }
}

最后，您可以通过在代码单元格中添加 raises-exception 标签，在单元格级别允许错误。这可以通过 Jupyter 界面完成，或者通过 {code-cell} 指令如下：

```{code-cell}
---
tags: [raises-exception]
---
print(thisvariabledoesntexist)
```

这将产生：

print(thisvariabledoesntexist)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[1], line 1
----> 1 print(thisvariabledoesntexist)

NameError: name 'thisvariabledoesntexist' is not defined

处理生成 stderr 的代码#

您可能还希望控制如何处理 stderr 输出。

或者，您可以使用 nb_output_stderr 配置值在全局配置级别配置如何处理 stdout。

您可以在 _config.yml 中为所有笔记本配置默认行为：

execute:
  stderr_output: show

其中值为以下之一：

"show"（默认）：显示所有 stderr（除非存在 remove-stderr 标签）
"remove"：移除所有 stderr
"remove-warn"：移除所有 stderr，但如果发现任何 stderr，则记录警告
"warn"、"error" 或 "severe"：如果发现任何 stderr，则在特定级别记录 stderr。

您还可以在单元格级别使用 remove-stderr 单元格标签移除 stderr，如下所示：

```{code-cell} ipython3
:tags: [remove-stderr]

import sys
print("这是一些 stdout")
print("这是一些 stderr", file=sys.stderr)
```

这将产生

import sys
print("这是一些 stdout")
print("这是一些 stderr", file=sys.stderr)

这是一些 stdout

处理生成 stdout 的代码#

与 stderr 类似，您可以使用 remove-stdout 标签在单元格级别移除 stdout，如下所示：

```{code-cell} ipython3
:tags: [remove-stdout]

import sys
print("这是一些 stdout")
print("这是一些 stderr", file=sys.stderr)
```

这将产生以下内容：

import sys
print("这是一些 stdout")
print("这是一些 stderr", file=sys.stderr)

合并 stdout 和 stderr 输出#

代码单元格中的代码可能通过 stdout 和 stderr 流打印输出。

这些输出可能以混合顺序出现，您可能希望它们被分组和排序以显示正确的 逻辑 顺序。

这可以通过使用 myst_nb 中的 nb_merge_streams 功能来实现。

您可以在 _config.yml 中启用此功能：

sphinx:
  config:
    nb_merge_streams: true

执行统计#

在执行笔记本时，MyST-NB 会在构建环境中存储某些统计数据。访问和可视化这些数据的最简单方法是使用 {nb-exec-table} 指令。

终端中的执行回溯#

可以将执行错误的回溯直接打印到终端中，而不是保存到日志文件中。如果您将书籍执行作为在线构建过程的一部分（例如，通过 GitHub Pages、ReadTheDocs 或 Netlify），这尤其有用。

在 _config.yml 中启用激活执行回溯：

sphinx:
  config:
    nb_execution_show_tb: True

有关更多信息，请参阅 MyST-NB 文档。

Document	Modified	Method	Run Time (s)	Status
basics/create	2024-11-01 15:41	cache	2.2	✅
content/code-outputs	2024-11-01 15:41	cache	0.93	✅
content/execute	2024-11-01 15:41	cache	1.1	✅
content/layout	2024-11-01 15:41	cache	0.92	✅
content/math	2024-11-01 15:42	cache	0.72	✅
content/proof	2024-11-01 15:42	cache	0.72	✅
content/references	2024-11-01 15:42	cache	0.72	✅
file-types/jupytext	2024-11-01 23:42	cache	4.06	✅
file-types/myst-notebooks	2024-11-01 15:42	cache	0.72	✅
file-types/notebooks	2024-11-01 23:42	cache	1.56	✅
interactive/hiding	2024-11-01 23:42	cache	1.26	✅
interactive/interactive	2024-11-01 23:42	cache	1.05	✅
interactive/launchbuttons	2024-11-01 15:42	cache	0.72	✅
interactive/thebe	2024-11-01 23:42	cache	1.1	✅
reference/cheatsheet	2024-11-01 23:42	cache	1.19	✅
start/overview	2024-11-01 23:42	cache	0.98	✅
structure/toc	2024-11-01 23:42	cache	1.19	✅