使用 Sphinx 建置手冊

本頁說明如何使用 Sphinx 文件引擎建置 Godot 手冊的本地副本。你可以產生本地 HTML 檔案，也能將文件匯出為 PDF、EPUB 或 LaTeX 格式。

在開始之前，請確認你已具備以下條件：

備註

Python 3 應該會附帶 pip3 指令。你可能需要使用 python3 -m pip``（Unix）或 ``py -m pip``（Windows）來取代 ``pip3。若這兩種方法都無法運作，請參考 確保已安裝 pip3。

  1. （可選） 建立虛擬環境。虛擬環境可以避免 requirements.txt 內的 Python 套件與系統上安裝的其他 Python 套件發生衝突。

    1. 建立虛擬環境：

      py -m venv godot-docs-venv

    2. 啟用虛擬環境：

      godot-docs-venv\Scripts\activate.bat

    3. （可選） 更新已預先安裝的套件：

      py -m pip install --upgrade pip setuptools

  2. 複製文件倉庫：

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

  3. 切換到文件倉庫目錄：

    cd godot-docs

  4. 安裝必要套件：

    pip3 install -r requirements.txt

  5. 建置文件：

    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

如果遇到 MemoryError 或 EOFError，可以刪除 classes/ 資料夾後重新執行 make。這麼做會讓最終的 HTML 文件中移除類別參考，但其他內容不受影響。

重要

如果刪除了 classes/ 資料夾，處理 pull request 時請勿使用 git add .，否則整個 classes/ 資料夾都會被標記為刪除。詳情請見 #3157。

效能提示

記憶體使用量

建置文件至少需要 8 GB 記憶體，才能避免使用虛擬記憶體（會拖慢速度）。如果你有 16 GB 以上記憶體，可以用下列指令加速編譯：

set SPHINXOPTS=-j2 && make html

你可以使用 -j auto 來啟用所有可用 CPU 執行緒，但如果執行緒數量很多，會大量佔用記憶體。例如在 32 執行緒的系統上，-j auto``（等同於 ``-j 32）僅 Sphinx 就可能需要 20 GB 以上的記憶體。

指定檔案清單

警告

本節在 Windows 上無法運作，因為倉庫使用的是簡化版 make.bat，而不是 GNU Make。若要在系統上取得 Linux 終端機，請考慮使用 Windows Subsystem for Linux (WSL)。

你可以指定要建置的檔案清單，這樣可以大幅加快編譯速度：

make html FILELIST='classes/class_node.rst classes/class_resource.rst'

你也可以利用 git 指令取得檔案清單。這樣可以自動取得自上次提交以來變更的所有檔名（這裡用 sed 把檔名串在同一行）。

make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"

你可以將 HEAD 換成 master，以取得自 master 分支以來變更的所有檔案：

make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"

如果有圖片被修改，輸出結果可能會出現相關警告，但建置流程仍會正常完成。