Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

使用 Sphinx 构建手册

本页面描述使用 Sphinx 文档引擎构建本地 Godot 手册的方法。你可以用它来获得本地的 HTML 文件以及诸如 PDF、EPUB、LaTeX 形式的文档。

在开始之前，请确保你已完成以下步骤：

Git
make（除非你在使用 Windows 系统）
Python 3

备注

Python 3 应该带有 pip3 命令。你可能需要输入 python3 -m pip（Unix）或 py -m pip（Windows）而不是 pip3。如果两种方法都失败了，请确保已安装 pip3。

（可选） 设置虚拟环境。虚拟环境可防止 requirements.txt 中的 Python 包与系统上安装的其他 Python 包之间的潜在冲突。
1. 创建虚拟环境：
  py -m venv godot-docs-venv
  python3 -m venv godot-docs-venv
2. 启动虚拟环境：
  godot-docs-venv\Scripts\activate.bat
  source godot-docs-venv/bin/activate
3. （可选） 更新预安装的软件包：
  py -m pip install --upgrade pip setuptools
  pip3 install --upgrade pip setuptools

克隆（clone）文档仓库：

git clone https://github.com/godotengine/godot-docs.git

将目录切换到文档仓库：
```
cd godot-docs
```
安装需要的软件包：
```
pip3 install -r requirements.txt
```
构建文档：
```
make html
```
备注

在 Windows 上，该命令将运行 make.bat 而不是 GNU Make（或其他替代方案）。

或者你也可以手动调用 sphinx-build 程序来构建文档：
```
sphinx-build -b html ./ _build/html
```

因为 classes/ 文件夹里包含了上百个文件，所以编译的过程会花上一些时间。详见性能提示。

完成后就可以在网页浏览器里打开 _build/html/index.html 查看文档了。

处理错误

如果你遇到了错误，可以试试以下命令：

make SPHINXBUILD=~/.local/bin/sphinx-build html

如果你遇到了 MemoryError 或者 EOFError，可以把 classes/ 文件夹删除然后重新执行 make。这样会在最终的 HTML 文档中删除类参考文档，其它内容还是一致的。

重要

如果你删除了 classes/ 文件夹，在处理 Pull Request（拉取请求）时请勿使用 git add .，否则整个 classes/ 文件夹的删除都会记录进你的提交之中。详见 #3157 <https://github.com/godotengine/godot-docs/issues/3157>。

性能提示

内存占用

磁盘交换会拖慢文档构建的速度，关闭后需要至少 8 GB 的内存。如果你有至少 16 GB 的内存，可以这样加速编译：

set SPHINXOPTS=-j2 && make html

make html SPHINXOPTS=-j2

您可以使用 -j auto 来使用所有可用的 CPU 线程，但是如果你有很多 CPU 线程，这可能会使用大量内存。例如，在具有 32 个 CPU 线程的系统上，-j auto（此处对应 -j 32 ）仅 Sphinx 就需要 20+ GB 的内存。

指定文件列表

你可以指定需要构建的文件列表，大幅加速编译：

make FILELIST='classes/class_node.rst classes/class_resource.rst' html