Beitrag zur Dokumentation

In dieser Anleitung wird erklärt, wie Sie zur Godot-Dokumentation beitragen können, sei es durch das Schreiben oder Überprüfen von Seiten.

Siehe auch

Wenn Sie Seiten oder die Klassenreferenz vom Englischen in andere Sprachen übersetzen wollen, lesen Sie Editor und Dokumentation übersetzen.

Erste Schritte

Um Seiten im Referenzhandbuch zu ändern oder zu erstellen, müssen Sie die .rst-Dateien im godot-docs GitHub Repository bearbeiten. Das Ändern dieser Seiten in einem Pull Request löst beim Mergen einen Rebuild der Online-Dokumentation aus.

Siehe auch

Für Erläuterungen zum Umgang mit Git und dem Workflow beim Pull Request, sehen Sie sich die Workflow eines Pull Requests-Seite an. Die meisten der dort für das godotengine/godot-Repository beschriebenen Schritte treffen ebenso auf das docs-Repository zu.

Warnung

Die Quelldateien der Klassenreferenz befinden sich im Godot-Engine Repository. Wir generieren den Abschnitt Klassenreferenz dieser Dokumentation daraus. Wenn Sie die Beschreibung einer Klasse, ihrer Methoden oder Propertys aktualisieren wollen, lesen Sie Beitragen zur Klassenreferenz.

Was ist die Godot-Dokumentation

Die Godot-Dokumentation ist als umfassendes Referenzhandbuch für die Godot-Spielengine gedacht. Sie soll keine Schritt-für-Schritt-Tutorials enthalten, mit Ausnahme von zwei Tutorials zur Spielerstellung im Abschnitt "Erste Schritte".

Wir bemühen uns, sachliche Inhalte in einer verständlichen und gut geschriebenen Sprache zu verfassen. Um einen Beitrag zu leisten, lesen Sie bitte auch:

  1. Leitlinien zum Schreiben. Dort finden Sie Regeln und Empfehlungen, um so zu schreiben, dass es jeder versteht.

  2. Inhaltliche Leitlinien. Es erklärt die Grundsätze, die wir bei der Erstellung der Dokumentation befolgen, und die Art des Inhalts, die wir akzeptieren.

Änderungen beitragen

Pull requests should use the master branch by default. Only make pull requests against other branches (e.g. 3.6 or 4.2) if your changes only apply to that specific version of Godot. After a pull request is merged into master, it will usually be cherry-picked into the current stable branch by documentation maintainers.

Dieses Git-Repository ist zwar weniger bequem zu bearbeiten als ein Wiki, aber wir schreiben dort unsere Dokumentation. Der direkte Zugriff auf die Quelldateien in einem Revisionskontrollsystem ist ein Vorteil, um die Qualität unserer Dokumentation zu gewährleisten.

Vorhandene Seiten bearbeiten

Um eine bestehende Seite zu bearbeiten, suchen Sie ihre .rst-Quelldatei und öffnen Sie sie in Ihrem bevorzugten Texteditor. Sie können dann die Änderungen committen, sie auf Ihren Fork pushen und einen Pull Request stellen. Beachten Sie, dass die Seiten in classes/ hier nicht bearbeitet werden sollten. Sie werden automatisch aus Godots XML-Klassenreferenz erzeugt. Siehe Beitragen zur Klassenreferenz für Details.

Siehe auch

Um das Handbuch zu erstellen und Änderungen auf Ihrem Computer zu testen, siehe Erstellen des Handbuchs mit Sphinx.

Seiten online bearbeiten

Sie können die Dokumentation online bearbeiten, indem Sie auf den Link Edit on GitHub in der oberen rechten Ecke jeder Seite klicken.

Auf diese Weise gelangen Sie zum GitHub-Texteditor. Sie müssen ein GitHub-Konto haben und sich anmelden, um ihn zu nutzen. Sobald Sie eingeloggt sind, können Sie Änderungen wie folgt vorschlagen:

  1. Drücken Sie auf den Edit on GitHub-Button.

  2. On the GitHub page you're taken to, make sure the current branch is "master". Click the pencil icon in the top-right corner near the Raw, Blame, and Delete buttons. It has the tooltip "Fork this project and edit the file".

  3. Bearbeiten Sie den Text mit dem Texteditor.

  4. Click "Commit changes...", summarize the changes you made and make sure to replace the placeholder "Update file.rst" by a short, but clear one-line description, as this is the commit title. Click the button Propose changes.

  5. Auf den folgenden Bildschirmen klicken Sie auf den Create pull request-Button, bis Sie eine Meldung wie Username wants to merge 1 commit into godotengine:master from Username:patch-1 sehen.

Bemerkung

If there are more commits than your own in the pull request it is likely that your branch was created using the wrong origin, due to "master" not being the current branch in step 2. You will need to rebase your branch to "master" or create a new branch.

Ein anderer Mitwirkender überprüft Ihre Änderungen und fügt sie in die Dokumente ein, wenn sie gut sind. Er kann auch Änderungen vornehmen oder Sie darum bitten, dies vor dem Mergen zu tun.

Hinzufügen neuer Seiten

Bevor Sie eine neue Seite hinzufügen, vergewissern Sie sich bitte, dass sie in die Dokumentation passt:

  1. Suchen Sie nach bestehenden Issues oder eröffnen Sie eine neue Issue, um zu sehen, ob die Seite notwendig ist.

  2. Stellen Sie sicher, dass es keine Seite gibt, die das Thema bereits behandelt.

  3. Lesen Sie Inhaltliche Leitlinien.

Um eine neue Seite hinzuzufügen, erstellen Sie eine .rst-Datei mit einem aussagekräftigen Namen in dem Abschnitt, dem Sie eine Datei hinzufügen möchten, z.B. tutorials/3d/light_baking.rst.

Sie sollten dann Ihre Seite in den entsprechenden "toctree" (Inhaltsverzeichnis, z.B. tutorials/3d/index.rst) einfügen. Fügen Sie Ihren neuen Dateinamen in einer neuen Zeile in die Liste ein, wobei Sie einen relativen Pfad und keine Erweiterung verwenden, z.B. hier light_baking.

Überschriften

Fangen Sie jede Seite stets mit der Überschrift an und einer internen Bezeichnung für den Sphinx-Verweis:

.. _doc_insert_your_title_here:

Insert your title here
======================

Die Referenz _doc_insert_your_title_here und der Titel sollten übereinstimmen.

Die Referenz ermöglicht die Verknüpfung der Seite per :ref:-Tag, so würde etwa :ref:`doc_insert_your_title_here` auf die obige Beispielseite verlinken (man beachte den fehlenden Unterstrich im Verweis).

Schreiben Sie Ihre Titel wie einfache Sätze, ohne jedes Wort groß zu schreiben:

  • Gut: Understanding signals in Godot

  • Schlecht: Understanding Signals In Godot

Nur bei Substantiven, Projekten, Personen und Node-Klassennamen sollte der erste Buchstabe groß geschrieben werden.

Sphinx und reStructuredText-Syntax

In der reST-Einführung von Sphinx und der offiziellen Referenz finden Sie Details zur Syntax.

Sphinx verwendet spezifische reST-Kommentare, um bestimmte Operationen auszuführen, wie die Definition des Inhaltsverzeichnisses (.. toctree::) oder Querverweise auf Seiten. Schauen Sie in die offizielle Sphinx-Dokumentation für weitere Details. Um zu lernen, wie man Sphinx-Direktiven wie .. note:: oder .. seealso:: benutzt, schauen Sie in die Sphinx-Direktiven-Dokumentation.

Hinzufügen von Bildern und Anhängen

Um Bilder hinzuzufügen, legen Sie sie bitte in einem img/-Ordner neben der .rst-Datei mit einem aussagekräftigen Namen ab und binden Sie sie mit in Ihre Seite ein:

.. image:: img/image_name.webp

Alternativ können Sie die Direktive figure verwenden, die dem Bild einen kontrastierenden Rahmen verleiht und es auf der Seite zentriert.

.. figure:: img/image_name.webp
    :align: center

Sie können auch Anhänge als Hilfsmaterial für ein Tutorial einfügen, indem Sie sie in einem files/-Ordner neben der .rst-Datei ablegen und dieses Inline-Markup verwenden:

:download:`file_name.zip <files/file_name.zip>`

Ziehen Sie in Erwägung, das Repository godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> für die Bereitstellung von Support-Materialien wie Projektvorlagen und Asset Packs zu verwenden. Sie können einen direkten Link zu dem generierten Archiv aus diesem Repository mit dem regulären Link-Markup verwenden:

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

Lizenz

Diese Dokumentation und alle darin enthaltenen Seiten werden unter den Bedingungen der Creative Commons Attribution 3.0 license (CC BY 3.0) veröffentlicht, mit Attribution an "Juan Linietsky, Ariel Manzur and the Godot community".

Durch das Beitragen zu dieser Dokumentation im GitHub-Repository akzeptieren Sie die Veröffentlichung Ihrer Inhalte unter dieser Lizenz.