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

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

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

  1. # On Linux and macOS
  2. make html
  4. # On Windows, you need to execute the ``make.bat`` file instead.
  5. make.bat html

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

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

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

  1. # On Linux/macOS
  2. make html SPHINXOPTS=-j2
  4. # On Windows
  5. 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 程序来构建文档：

  1. sphinx-build -b html ./ _build

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

  1. sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst

使用 Sphinx 和 virtualenv 构建

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

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

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