Sphinx 高级用法

Sphinx 高级用法#

Jupyter Book 使用出色的文档工具 Sphinx 来构建您的书籍并管理引用、交叉引用和可扩展性。

尽管 Jupyter Book 预配置了多个 Sphinx 扩展，但高级用户可能希望添加自己的扩展和配置。本页介绍如何实现这一点。

Warning

添加您自己的 Sphinx 配置和扩展可能会导致 Jupyter Book 的行为不可预测。请谨慎使用！

自定义 Sphinx 扩展#

要在构建 Jupyter Book 时启用您自己的 Sphinx 扩展，请在 _config.yml 文件中使用以下配置：

sphinx:
  extra_extensions:
   - extension1
   - extension2

列出的任何扩展都将在构建时追加到 Sphinx 扩展列表中。

Note

确保您已将扩展安装在您的机器上，否则 Sphinx 将不知道如何构建这些扩展。

示例：`sphinx-inline-tabs`#

默认情况下，Jupyter Book 通过 sphinx-design 提供选项卡功能。Sphinx 生态系统中有其他不同功能的选项卡包。其中一个包是 sphinx-inline-tabs，它允许在页面上同步切换选项卡。

sphinx-inline-tabs 默认不包含在 Jupyter Book 中，但我们可以通过 Jupyter Book 激活它，如下所示：

安装 sphinx-inline-tabs。以下是安装命令：
```
pip install sphinx-inline-tabs
```

将 sphinx-inline-tabs 内容添加到您的书籍中。以下是使用 MyST Markdown 的示例：

前两个选项卡展示定义函数的示例。

````{tab} Python
```python
def main():
    return
```
````
````{tab} C++
```c++
int main(const int argc, const char **argv) {
  return 0;
}
```
````

后两个选项卡展示打印的示例。

````{tab} Python
```python
print("Hello World!")
```
````

````{tab} C++
```c++
#include <iostream>

int main() {
  std::cout << "Hello World!" << std::endl;
}
```
````

在 _config.yml 中激活 sphinx-inline-tabs。 sphinx-inline-tabs 文档说明我们通过添加 extensions = ["sphinx_inline_tabs"] 在 Sphinx 中激活它，因此我们将其添加到 Jupyter Book 中，如下所示：
```
sphinx:
  extra_extensions:
  - sphinx_inline_tabs
```

现在，Jupyter Book 将知道如何解释 {tab} 指令（以及 sphinx-inline-tabs 支持的其他任何指令）。

例如，以下是上面粘贴的选项卡代码的渲染版本：

前两个选项卡展示定义函数的示例。

Python

def main():
    return

C++

int main(const int argc, const char **argv) {
  return 0;
}

后两个选项卡展示打印的示例。

Python

print("Hello World!")

C++

#include <iostream>

int main() {
  std::cout << "Hello World!" << std::endl;
}

本地 Sphinx 扩展#

[Sphinx 能够通过添加额外的目录到 Python 路径使用本地扩展](https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html#using-the-extension)。您可以通过在 _config.yml 文件中将它们指定为 local_extensions 来使用本地扩展。

要添加需要路径的本地扩展，请使用：

sphinx:
  local_extensions:
    <name>: <path>

这将追加到 Jupyter Book 已加载的扩展列表中，并更新 sys.path，以便可以找到本地扩展。

手动 Sphinx 配置#

您也可以直接覆盖 Sphinx 通常让您在 conf.py 中配置的键值对。为此，请使用 _config.yml 中的以下部分：

sphinx:
  config:
    key1: value1
    key2: value2

默认情况下，sphinx: config: 部分中的任何值都将完全替换 Jupyter Book 设置的默认配置。例如，如果值是字典，整个字典将被替换，而不仅仅是您在 _config.yml 中指定的键。

或者，您可以使用 sphinx: 部分中的 recursive_update 选项递归地覆盖默认配置。在这种情况下，sphinx: config: 中指定的仅您指定的值将覆盖其默认值，而您未指定的配置将保持不变。您可以按如下方式触发此行为：

sphinx:
  recursive_update: true
  config:
    # 要递归添加的 Sphinx 配置选项

此选项默认为 false。

Tip

如果您希望检查生成的配置的 conf.py 表示形式，

选择一个自定义的 Sphinx 主题

Sphinx 支持许多不同的主题来控制输出的外观。Jupyter Book 默认使用 Sphinx Book Theme，但您可以通过直接配置 Sphinx 为您的 Jupyter Book 使用任何 Sphinx 主题。

例如，如果您希望使用 PyData Sphinx Theme，您可以通过以下方式安装该主题：

pip install pydata-sphinx-theme

然后这样配置您的书籍：

...
sphinx:
  config:
    html_theme: pydata_sphinx_theme
...

当您构建书籍时，将使用 PyData 主题。在这种情况下，您应查阅 PyData 主题文档以获取有关如何配置它的信息。

Warning

虽然您可以选择任何主题，但某些 Jupyter Book 配置仅适用于 Sphinx Book Theme，因此如果您选择自定义主题，某些功能可能无法使用。例如，大多数 Sphinx 主题不支持启动按钮。

精细控制解析和执行#

正如在Jupyter Book 的组成部分中所讨论的，Jupyter Book 的两个主要组成部分是 Sphinx 扩展；用于 Markdown 解析的 MyST-Parser 和用于笔记本执行和输出渲染的 MyST-NB。

这两个扩展通过 Sphinx 配置高度可定制。它们的某些配置已经在 _config.yml 中暴露，但您也可以直接设置配置，请参见：

MyST-Parser 配置选项
MyST-NB 配置选项

定义 TeX 宏#

您可以通过在 TeX 块的 Macros 选项下定义它们来为整本书添加 LaTeX 宏。例如，以下两个宏已在 Sphinx 配置中预定义：

sphinx:
  config:
    mathjax3_config:
      tex:
        macros:
          "N": "\\mathbb{N}"
          "floor": ["\\lfloor#1\\rfloor", 1]
          "bmat" : ["\\left[\\begin{array}"]
          "emat" : ["\\end{array}\\right]"]

您还可以通过在文件开头的 math 指令下引入它们来为特定文件定义 TeX 宏。例如：

```{math}

\newcommand\N{\mathbb{N}}
\newcommand\floor[1]{\lfloor#1\rfloor}
\newcommand{\bmat}{\left[\begin{array}}
\newcommand{\emat}{\end{array}\right]}
```

这些命令可以在 math 指令、$$ 或行内 $ 中使用。例如：

$$
A = \bmat{} 1 & 1 \\ 2 & 1\\ 3 & 2 \emat{},\ b=\bmat{} 2\\ 3 \\ 4\emat{},\ \gamma = 0.5
$$

将被渲染为：

\[\begin{split} A = \bmat{} 1 & 1 \\ 2 & 1\\ 3 & 2 \emat{},\ b=\bmat{} 2\\ 3 \\ 4\emat{},\ \gamma = 0.5 \end{split}\]

从 CLI 启用自定义的 Sphinx 构建器#

您可以使用以下命令为自定义构建器启动构建：

jb build <project> --builder=custom --custom-builder=<builder-name>

高级 sphinx 用户可能会找到一个扩展，该扩展从 Sphinx AST 构建不同类型的输出，例如 sphinx-tojupyter，这是一个仅包含 basic Markdown 的笔记本构建扩展。

Warning

sphinx-tojupyter 将在 jupyter 笔记本中提供 myst 语法渲染支持后被弃用。

您可以通过将其添加到 _config.yml 中来启用 jupyter 构建器：

sphinx:
  extra_extensions: [sphinx_tojupyter]

并通过 jupyter-book 使用 custom 选项：

jb build <project> --builder=custom --custom-builder=jupyter

Warning

开发者： 当使用其他输出目标时，该包需要支持为 myst_nb 兼容性指定 mime 类型优先级。

有关更多详细信息，请参见此代码。

Sphinx 高级用法

Contents

Sphinx 高级用法#

自定义 Sphinx 扩展#

示例：sphinx-inline-tabs#

本地 Sphinx 扩展#

手动 Sphinx 配置#

选择一个自定义的 Sphinx 主题

精细控制解析和执行#

定义 TeX 宏#

从 CLI 启用自定义的 Sphinx 构建器#

示例：`sphinx-inline-tabs`#