Erstellen des Handbuchs mit Sphinx

Auf dieser Seite wird erklärt, wie Sie eine lokale Kopie des Godot-Handbuchs mithilfe der Sphinx docs-Engine erstellen können. Dies ermöglicht Ihnen, lokale HTML-Dateien zu haben und die Dokumentation z. B. als PDF-, EPUB- oder LaTeX-Datei zu erstellen.

Um zu beginnen, müssen Sie:

  1. Klonen Sie das godot-docs-Repository.

  2. Installieren Sie Sphinx

  3. Um die Dokumente als HTML-Dateien zu erstellen, installieren Sie das readthedocs.org design.

  4. Installieren Sie die Sphinx-Erweiterungen, die in godot-docs repository requirements.txt definiert sind.

Wir empfehlen die Verwendung von pip, dem Paketmanager von Python, um alle diese Werkzeuge zu installieren. Er wird mit Python vorinstalliert. Stellen Sie sicher, dass Sie Python 3 installieren und verwenden. Hier sind die Befehle, um das Repository zu klonen und dann alle Anforderungen zu installieren.

Bemerkung

Möglicherweise müssen Sie anstelle von pip3 python3 -m pip (Unix) bzw. py -m pip (Windows) schreiben. Schlagen beide Ansätze fehlt, so überprüfen Sie bitte, ob Sie pip3 installiert haben <https://pip.pypa.io/en/stable/installation/>`__.

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

Wenn die Programme installiert sind, können Sie die HTML-Dokumentation aus dem Stammordner dieses Repositorys mit dem folgenden Befehl erstellen:

# On Linux and macOS
make html

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

Wenn Sie auf Fehler stoßen, können Sie den folgenden Befehl versuchen:

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

Das Erstellen der Dokumentation erfordert mindestens 8 GB RAM, um ohne Festplattenswapping zu laufen, was es verlangsamt. Wenn Sie mindestens 16 GB RAM haben, können Sie die Kompilierung beschleunigen, indem Sie ausführen:

# On Linux/macOS
make html SPHINXOPTS=-j2

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

Die Kompilierung wird einige Zeit dauern, da der Ordner classes/ hunderte von Dateien enthält.

Sie können dann die Dokumentation durchsuchen, indem Sie _build/html/index.html in Ihrem Webbrowser öffnen.

Falls Sie einen MemoryError oder EOFError erhalten, können Sie den Ordner classes/ entfernen und make erneut ausführen. Dadurch werden die Klassenreferenzen aus der endgültigen HTML-Dokumentation entfernt, aber der Rest bleibt intakt.

Bemerkung

Wenn Sie den Ordner classes/ löschen, verwenden Sie nicht git add, wenn Sie an einer Pull-Request arbeiten, sonst wird der gesamte Ordner classes/ beim Commit entfernt. Siehe #3157 für weitere Details.

Alternativ können Sie die Dokumentation auch erstellen, indem Sie das Programm sphinx-build manuell ausführen:

sphinx-build -b html ./ _build

You can also specify a list of files to build, which can greatly speed up compilation:

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

Komilieren mit Sphinx und virtualenv

Wenn Sie Ihre Sphinx-Installation auf das Projekt beschränken möchten, können Sie sphinx-build mit virtualenv installieren. Führen Sie dazu diesen Befehl aus dem Stammordner dieses Repositorys aus:

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

Führen Sie dann make html wie oben gezeigt aus.