使用 Sphinx 构建手册

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

  1. godot-docs 仓库 。
  2. Sphinx
  3. readthedocs.org 主题 。
  4. godot-docs 仓库 的 requirements.txt 文件中定义的 Sphinx 扩展。 pip 来安装这些工具，这个管理器是 Python 自带的。请确保安装并使用的是 Python 3。以下为用来克隆仓库并安装所需工具的命令。 注解 python3 -m pip（Unix）或 py -m pip（Windows）而不是 pip3 。如果这两种方法都失败了，请检查是否安装了 pip3。
    1. git clone https://github.com/godotengine/godot-docs.gitpip3 install -r requirements.txt
    安装好这些程序后，你就可以在该仓库的根目录构建 HTML 文档了。使用如下命令：
    1. # On Linux and MacOSmake html# On Windows, you need to execute the ``make.bat`` file instead.make.bat html
    如果你遇到了错误，可以试试以下命令：
    1. make SPHINXBUILD=~/.local/bin/sphinx-build html
    磁盘交换会拖慢文档构建的速度，关闭后需要至少 8 GB 的内存。如果你有至少 16 GB 的内存，可以这样加速编译：
    1. # On Linux/macOSmake html SPHINXOPTS=-j2# On Windowsset 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

    使用 Sphinx 和 virtualenv 构建

    如果你希望安装的 Sphinx 仅限于当前项目，可以用 virtualenv 来安装 sphinx-build。在仓库根目录执行这个命令即可：
    1. virtualenv --system-site-packages env/. env/bin/activatepip3 install -r requirements.txt
    make html。