Jupyter Book 和 Sphinx 之间的关系

Jupyter Book 和 Sphinx 之间的关系#

Jupyter Book 在底层大量使用了 Sphinx。事实上，可以将 Jupyter Book 视为 Sphinx 的一种观点鲜明的发行版。以下是对 Jupyter Book 和 Sphinx 之间关系的简要解释。

什么是 Sphinx？#

Sphinx 是 一个开源的文档引擎，在 Python 社区中已经流行了近十年。Sphinx 基于 Docutils 核心 Python 包，该包为 Python 中的文档提供了一种数据结构。Docutils 没有多页面文档的概念，因此 Sphinx 使用了基本的 Docutils 数据结构，并包含了多页面功能，如交叉引用、引用和多页目录表。

Sphinx 主要使用一种称为 reStructuredText 的标记语言来编写文档。这与 Markdown 类似，但不太流行且更具灵活性。相比之下，Jupyter Book 使用 MyST Markdown，这是为了提供 rST 的灵活性，同时让喜欢使用 Markdown 的人也能受益。

Sphinx 也具有高度的可扩展性——开发者可以编写扩展和主题，使 Sphinx 能够实现核心工具中未内置的额外功能。

See also

有关 Sphinx 的更多信息，请查看 ReadTheDocs Sphinx 教程。

Jupyter Book 是 Sphinx 的一个发行版#

Jupyter Book 几乎所有功能都使用 Sphinx 来实现。例如——解析交叉引用、生成 HTML 或 PDF、读取源文件和 Jupyter Notebook 等。它通过激活 Executable Books 团队 创建的多个Sphinx 扩展来实现这一点。这些扩展增强了 Sphinx 的功能，使其能够处理 Jupyter Book 的使用场景。

示例：MyST Markdown

让我们以 MyST Markdown 为例。如前所述，Sphinx 默认无法读取 Markdown 文件，但我们希望用户能够这样做。我们可以通过安装并激活一个 Markdown 解析器来扩展 Sphinx 的功能。MyST Parser 提供了一个 Sphinx 扩展，允许 Sphinx 读取 MyST Markdown。通过安装这个扩展，并将其添加到我的 Sphinx 项目扩展列表中，Sphinx 现在将自动读取 .md 文件。

当 Jupyter Book 构建一本书时，它首先激活这一组核心的 Jupyter Book 特定 Sphinx 扩展。然后，它将你的 _config.yml 转换为 Sphinx 自己的配置语言，并使用 Sphinx 的构建命令来构建这本书。你可以通过运行以下命令查看 Jupyter Book 使用的 Sphinx 配置文件：

jupyter-book config sphinx path/to/mybook/

Jupyter Book 与 Sphinx 有何不同？#

除了预激活一些扩展外，Jupyter Book 在其他几个方面也与 Sphinx 有所不同。

目录表 - 在 Sphinx 中，文档的结构由名为 {toctree} 的指令决定。这些指令与页面内容一起放置，是作者告诉 Sphinx 该页面下有哪些子章节的方式。Jupyter Book 则使用一个单一的目录文件（称为 _toc.yml）来定义书籍的结构。

YAML 配置 - 在 Sphinx 中，所有配置都由一个名为 conf.py 的 Python 文件定义。Jupyter Book 则使用 YAML 文件，并包含一些特定于 Jupyter Book 的键（但在构建时会转换为 Sphinx 配置）。有关 Jupyter Book 如何将其自身配置转换为 Sphinx 配置的详细信息，请参见 yaml_to_sphinx 函数。

命令行接口 - 最后，Sphinx 有多个命令行接口来控制其功能——最流行的是 sphinx-build。Jupyter Book 提供了自己的 CLI（jupyter-book build）来处理上述额外功能。

如何在 Sphinx 中复制 Jupyter Book 的功能#

由于 Jupyter Book 的大部分功能来自 Sphinx 扩展，这意味着更广泛的 Sphinx 社区可以复制 Jupyter Book 的许多功能。如果你想对构建过程有更多控制，或者需要在构建过程中集成更复杂的步骤，你可能会这样做。

以下是 Jupyter Book 激活的 Sphinx 扩展的简要概述：

  • MyST-NB - 在 Sphinx 中读取 Jupyter Notebook 以及执行它们的功能。

  • MyST Parser - 用于将CommonMark和MyST Markdown文件解析为Sphinx的功能。虽然未明确提供，但由MyST-NB激活。

  • Sphinx Design - 提供用于Jupyter Book文档中使用的UI组件的Sphinx指令。

  • Sphinx Book Theme - 定义Jupyter Book外观和感觉以及其一般布局的Sphinx主题。

要了解Jupyter Book如何配置Sphinx，您应查看config.py模块。例如，这里定义了默认的Sphinx配置。

如果您希望在Sphinx中复制Jupyter Book的功能，您应创建一个Sphinx站点，并将此配置复制到您的conf.py文件中。当您构建Sphinx站点时，它应与Jupyter Book表现非常相似。