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:
Klonen Sie das godot-docs-Repository.
Installieren Sie Sphinx
Um die Dokumente als HTML-Dateien zu erstellen, installieren Sie das readthedocs.org design.
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.