Up to date

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

使用 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. 创建虚拟环境：
  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
```
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 的内存，可以这样加速编译：

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