Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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.

Bevor Sie beginnen, vergewissern Sie sich, dass Sie diese Dinge haben:

Bemerkung

Python 3 sollte mit dem Befehl pip3 ausgeliefert werden. Möglicherweise müssen Sie python3 -m pip (Unix) oder py -m pip (Windows) anstelle von pip3 schreiben. Wenn beide Ansätze scheitern, stellen Sie sicher, dass Sie pip3 installiert haben.

  1. (Optional) Richten Sie eine virtuelle Umgebung ein. Virtuelle Umgebungen verhindern mögliche Konflikte zwischen den Python-Paketen in requirements.txt und anderen Python-Paketen, die auf Ihrem System installiert sind.

    1. Erstellen Sie die virtuelle Umgebung:

      py -m venv godot-docs-venv

    2. Aktivieren Sie die virtuelle Umgebung:

      godot-docs-venv\Scripts\activate.bat

    3. (Optional) Aktualisieren Sie vorinstallierte Pakete:

      py -m pip install --upgrade pip setuptools

  2. Klonen Sie das Docs-Repository:

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

  3. Wechseln Sie in das Verzeichnis des Docs-Repository:

    cd godot-docs

  4. Installieren Sie die erforderlichen Pakete:

    pip3 install -r requirements.txt

  5. Erstellen Sie die Dokumente:

    make html

    Bemerkung

    Unter Windows wird dieser Befehl make.bat anstelle von GNU Make (oder einer Alternative) ausführen.

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

    sphinx-build -b html ./ _build/html

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

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

Umgang mit Fehlern

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

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

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

Wichtig

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

Hinweise zur Performance

RAM-Verbrauch

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

set SPHINXOPTS=-j2 && make html

Sie können -j auto verwenden, um alle verfügbaren CPU-Threads zu nutzen, aber dies kann eine Menge RAM verbrauchen, wenn Sie viele CPU-Threads haben. Auf einem System mit 32 CPU-Threads kann zum Beispiel -j auto (was hier -j 32 entspricht) 20+ GB RAM allein für Sphinx benötigen.

Angeben einer Liste von Dateien

Sie können eine Liste der zu erstellenden Dateien angeben, was die Kompilierung erheblich beschleunigen kann:

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