Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

使用 Sphinx 构建手册¶

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

Before you get started, make sure that you have:

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.

(Optional) Set up a virtual environment. Virtual environments prevent potential conflicts between the Python packages in requirements.txt and other Python packages that are installed on your system.
1. Create the virtual environment:
  py -m venv godot-docs-venv
  python3 -m venv godot-docs-venv
2. Activate the virtual environment:
  godot-docs-venv\Scripts\activate.bat
  source godot-docs-venv/bin/activate
3. (Optional) Update pre-installed packages:
  py -m pip install --upgrade pip setuptools
  pip3 install --upgrade pip setuptools

Clone the docs repo:

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

Change directory into the docs repo:
```
cd godot-docs
```
Install the required packages:
```
pip3 install -r requirements.txt
```
Build the docs:
```
make html
```
备注

On Windows, that command will run make.bat instead of GNU Make (or an alternative).

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

The compilation will take some time as the classes/ folder contains hundreds of files. See Hints for performance.

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

Dealing with errors¶

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

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>。

Hints for performance¶

RAM usage¶

磁盘交换会拖慢文档构建的速度，关闭后需要至少 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.

Specifying a list of files¶

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