使用 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

If you get a MemoryError or EOFError, you can remove the classes/ folder and run make again. This will drop the class references from the final HTML documentation, but will keep the rest intact.

重要

如果你删除了 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 的内存。

指定文件列表

警告

This section will not work on Windows, since the repository is using a simplified make.bat script instead of the real GNU Make program. If you would like to get a Linux terminal on your system, consider using Windows Subsystem for Linux (WSL).

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

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

The list of files can also be provided by the git command. This way you can automatically get the names of all files that have changed since the last commit (sed is used to put them on the same line).

make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"

You can replace HEAD with master to return all files changed from the master branch:

make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"

If any images were modified, the output will contain some warnings about them, but the build will proceed correctly.