使用 Sphinx 构建手册
- 处理错误
- 性能提示
  - 内存占用
  - 指定文件列表

使用 Sphinx 构建手册

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

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

Git
make (unless you’re using Windows)
Python 3

备注

Python 3 should come with the pip3 command. You may need to write python3 -m pip (Unix) or py -m pip (Windows) instead of pip3. If both approaches fail, make sure that you have pip3 installed.

（可选） 设置虚拟环境。虚拟环境可防止 requirements.txt 中的 Python 包与系统上安装的其他 Python 包之间的潜在冲突。
1. 创建虚拟环境：
  
  WindowsOther platforms
```
py -m venv godot-docs-venv
```
```
python3 -m venv godot-docs-venv
```
2. 启动虚拟环境：
  
  WindowsOther platforms
```
godot-docs-venv\Scripts\activate.bat
```
```
source godot-docs-venv/bin/activate
```
3. （可选） 更新预安装的软件包：
  
  WindowsOther platforms
```
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
```
Install the required packages:
```
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 的内存，可以这样加速编译：

WindowsOther platforms

set SPHINXOPTS=-j2 && make html

make html SPHINXOPTS=-j2

You can use -j auto to use all available CPU threads, but this can use a lot of RAM if you have a lot of CPU threads. For instance, on a system with 32 CPU threads, -j auto (which corresponds to -j 32 here) can require 20+ GB of RAM for Sphinx alone.

指定文件列表

You can specify a list of files to build, which can greatly speed up compilation:

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