使用 Sphinx 构建手册

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

开始前你需要:

  1. 克隆 godot-docs 仓库

  2. 安装 Sphinx

  3. 如果要构建 HTML 格式的文档,安装 readthedocs.org 主题

  4. 安装 godot-docs 仓库requirements.txt 文件中定义的 Sphinx 扩展。

我们推荐使用 Python 的包管理器 pip 来安装这些工具,这个管理器是 Python 自带的。请确保安装并使用的是 Python 3。以下为用来克隆仓库并安装所需工具的命令。

备注

你可能需要写 python3 -m pip(Unix)或 py -m pip(Windows)而不是 pip3 。如果这两种方法都失败了,请检查是否安装了 pip3

git clone https://github.com/godotengine/godot-docs.git
pip3 install -r requirements.txt

安装好这些程序后,你就可以在该仓库的根目录构建 HTML 文档了。使用如下命令:

# On Linux and macOS
make html

# On Windows, you need to execute the ``make.bat`` file instead.
make.bat html

如果你遇到了错误,可以试试以下命令:

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

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

# On Linux/macOS
make html SPHINXOPTS=-j2

# On Windows
set SPHINXOPTS=-j2 && make html

因为 classes/ 文件夹里包含了上百个文件,所以编译的过程会花上一些时间。

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

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

备注

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

或者你也可以手动调用 sphinx-build 程序来构建文档:

sphinx-build -b html ./ _build

使用 Sphinx 和 virtualenv 构建

如果你希望安装的 Sphinx 仅限于当前项目,可以用 virtualenv 来安装 sphinx-build。在仓库根目录执行这个命令即可:

virtualenv --system-site-packages env/
. env/bin/activate
pip3 install -r requirements.txt

然后就可以和之前一样执行 make html