Beitrag zur Klassenreferenz

Bemerkung

Diese Anleitung ist auch verfügbar als Videoanleitung auf Youtube .

Godot wird mit vielen Nodes und Singletons geliefert, um Ihnen bei der Entwicklung Ihrer Spiele zu helfen. Jedes ist eine Klasse, dokumentiert in Klassenreferenz. Diese Referenz ist für jeden der die Engine lernt unerlässlich: Sie ist sowohl online als auch in der Engine verfügbar.

Aber sie ist nicht vollständig. Einigen Methoden, Variablen und Signale fehlen die Beschreibungen. Andere haben sich mit den aktuellen Veröffentlichungen verändert und brauchen Anpassungen. Die Entwickler können nicht die gesamte Referenzdokumentation alleine schreiben. Godot braucht Sie und alle anderen um dabei zu helfen.

Wichtig: Wenn Sie größere Änderungen oder einen größeren Beitrag planen, ist es normalerweise eine gute Idee, den Sachverhalt in einem kurzen Kommentar mitzuteilen, damit andere informiert sind und nicht anfangen an der gleichen Sache zu arbeiten.

Siehe auch

Sie sind sich nicht sicher, wo Sie anfangen sollen, Beiträge zu leisten? Sehen Sie sich den aktuellen Abschlussstatus der Klassenreferenz hier an.

Wie man dazu beiträgt

Die Klassenreferenz befindet sich in den folgenden XML-Dateien im GitHub-Repository von Godot: doc/classes/.

Es gibt 5 Schritte zum Aktualisieren der Klassenreferenz (vollständige Anleitung unten):

  1. Fork Godot's repository
  2. Klonen Sie Ihren Fork auf Ihrem Computer
  3. Bearbeiten Sie die Klassendatei in doc/classes/, um Dokumentation zu schreiben
  4. Übernehmen Sie Ihre Änderungen und schieben Sie sie an Ihre Fork
  5. Stellen Sie eine Pull-Anfrage im Godot-Repository

Warnung

Verwenden Sie immer diese XML-Dateien, um die API-Referenz zu bearbeiten. Bearbeiten Sie nicht die generierten .rst-Dateien in der Online-Dokumentation, die im Repository godot-docs gehostet wird.

Beginnen Sie mit GitHub

Wenn Sie Git und GitHub noch nicht kennen, hilft Ihnen dieses Handbuch beim Einstieg. Sie werden lernen:

  • Forken und klonen des Godot Repository
  • Halten Sie Ihren Fork mit anderen Beitragenden auf dem Laufenden
  • Erstellen Sie einen Pull Request, damit Ihre Verbesserungen in den offiziellen Dokumenten erscheinen

Bemerkung

Wenn Sie neu bei Git sind, dem Versionskontrollsystem, das Godot benutzt, gehen Sie GitHubs interaktive Anleitung durch. Sie werden einige wichtige Vokabeln lernen und ein Gefühl für das Werkzeug bekommen.

Godot forken

Forke die Godot-Engine in ein eigenes GitHub-Repository.

Klonen Sie das Repository auf Ihren Computer:

git clone https://github.com/your_name/godot.git

Erstellen Sie einen neuen Zweig um Ihre Änderungen vorzunehmen. Das macht es sehr viel einfacher, Ihre Verbesserungen mit anderen Autoren des Dokuments zu synchronisieren. Es ist auch einfacher, Ihr Repository aufzuräumen, wenn Sie auf irgendwelche Probleme mit Git stoßen.

git checkout -b your-new-branch-name

Der neue Zweig ist derselbe wie Ihr Hauptzweig, bis Sie beginnen API-Dokumente zu schreiben. Im Ordner doc/` finden Sie die Klassenreferenz.

Wie Sie Ihren lokalen Klon auf dem Laufenden halten können

Andere Autoren tragen zu Godots Dokumentation bei. Ihr lokales Repository fällt dahinter zurück, und Sie müssen es synchronisieren. Besonders wenn andere Mitwirkende die Klassenreferenz aktualisieren, während Sie daran arbeiten.

Fügen Sie zuerst ein upstream git remote hinzu, mit dem Sie arbeiten können. Remotes sind Links zu Online-Repositorien, von denen Sie neue Dateien herunterladen können.

git remote add upstream https://github.com/godotengine/godot

Sie können die Liste aller Remote-Server überprüfen mit:

git remote -v

Sie sollten zwei haben: origin, Ihr Fork auf GitHub, die Git standardmäßig hinzufügt, und `upstream, die Sie gerade hinzugefügt haben:

origin  https://github.com/your_name/godot.git (fetch)
origin  https://github.com/your_name/godot.git (push)
upstream        https://github.com/godotengine/godot.git (fetch)
upstream        https://github.com/godotengine/godot.git (push)

Geben Sie jedes Mal, wenn Sie Ihren Branch mit dem Zustand des upstream Repository synchronisieren möchten, ein:

git pull --rebase upstream master

Dieser Befehl holt zunächst die neueste Version des Godot-Repositorys herunter. Dann wendet er Ihre lokalen Änderungen wieder darauf an.

Wenn Sie Änderungen vorgenommen haben, die Sie nicht in Ihrem lokalen Zweig beibehalten wollen, verwenden Sie stattdessen die folgenden Befehle:

git fetch upstream
git reset --hard upstream master

Warnung: Der obige Befehl setzt Ihren Zweig auf den Stand des upstream master-Zweigs zurück. Er verwirft alle lokalen Änderungen. Stellen Sie sicher, dass Sie diesen Befehl nur ausführen, bevor Sie wichtige Änderungen vornehmen.

Eine andere Möglichkeit ist, den Zweig, an dem Sie gerade arbeiten, zu löschen, den Master-Zweig mit dem Godot-Repository zu synchronisieren und einen neuen Zweig zu erstellen:

git checkout master
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name

Wenn Sie sich mittlerweile verloren fühlen, kommen Sie in unsere IRC-Kanäle und bitten Sie um Hilfe. Erfahrene Git-Benutzer werden Ihnen zur Hand gehen.

Aktualisieren der Dokumentationsvorlage

Wenn Klassen im Quellcode geändert werden, kann die Dokumentationsvorlage veraltet sein. Um sicherzustellen, dass Sie eine aktuelle Version bearbeiten, müssen Sie zunächst Godot kompilieren (Sie können der Seite Einführung in das Buildsystem folgen), und dann den folgenden Befehl ausführen (unter der Annahme eines 64-Bit-Linux):

./bin/godot.x11.tools.64 --doctool .

Die XML-Dateien in doc/classes sollten dann mit den aktuellen Funktionen der Godot Engine auf dem neuesten Stand sein. Sie können dann mit dem Befehl git diff überprüfen, was sich geändert hat. Wenn es Änderungen an anderen Klassen als der, die Sie dokumentieren möchten, gibt, übertragen Sie bitte zuerst diese Änderungen, bevor Sie mit der Bearbeitung der Vorlage beginnen:

git add doc/classes/*.xml
git commit -m "Sync classes reference template with current code base"

Sie können diese Datei jetzt bearbeiten, um Inhalte hinzuzufügen.

Beachte: Wenn dies bereits kürzlich von einem anderen Beitragenden gemacht wurde, musst Du nicht zwingend alle diese Schritte durchgehen (außer Du weißt, dass die Klasse, die Du vorhast zu editieren, bereits kürzlich erst bearbeitet worden ist).

Pushe und erstelle eine Pull Request

Sobald deine Änderungen abgeschlossen sind, pushe die Änderungen auf dein GitHub-Repository:

git add doc/classes/<edited_file>.xml
git commit -m "Explain your modifications."
git push

Wenn das erledigt ist, kannst du über die GitHub-Benutzeroberfläche deines Godot-Forks eine Pull-Request stellen.

Warnung

Obwohl Sie Dateien auf GitHub bearbeiten können, wird dies nicht empfohlen. Da Hunderte von Mitwirkenden an Godot arbeiten, muss die Git-Geschichte sauber bleiben. Jedes Commit sollte alle damit verbundenen Verbesserungen bündeln, die Sie an der Klassenreferenz vornehmen, eine neue Funktion, Fehlerbehebungen ... Wenn Sie von GitHub aus arbeiten, wird jedes Mal beim speichern ein neuer Zweig und eine Pull-Anforderung erstellt. Wenn ein paar Tagen vergehen, bevor Ihre Änderungen überprüft wurden, können Sie nicht sauber auf die neueste Version des Repositorys aktualisieren. Außerdem ist es schwieriger, saubere Einrückungen von GitHub fernzuhalten. Und sie sind sehr wichtig in den Dokumenten.

TL;DR: Wenn du nicht genau weißt, was du tust, bearbeite keine Dateien aus GitHub.

Wie man Klassen-XML bearbeitet

Bearbeite die Datei für deine gewählte Klasse in doc/classes/, um die Klassenreferenz zu aktualisieren. Der Ordner enthält eine XML-Datei für jede Klasse. Die XML-Datei listet die Konstanten und Methoden auf, die du in der Klassenreferenz findest. Godot generiert und aktualisiert das XML automatisch.

Bearbeite sie mit deinem bevorzugten Texteditor. Wenn du einen Code-Editor verwendest, stelle sicher, dass er den Einrückungsstil nicht verändert: Tabs für das XML und 4 Leerzeichen innerhalb von Blöcken im BBCode-Stil. Mehr dazu weiter unten.

Wenn du überprüfen musst, ob die vorgenommenen Änderungen in der generierten Dokumentation korrekt sind, builde Godot wie beschrieben hier, starte den Editor und öffne die Hilfe für die modifizierte Seite.

Wie man eine Klassenreferenz schreibt

Jede Klasse hat eine kurze und eine lange Beschreibung. Die Kurzbeschreibung befindet sich immer oben auf der Seite, während die vollständige Beschreibung unterhalb der Liste der Methoden, Variablen und Konstanten liegt. Methoden, Mitgliedsvariablen, Konstanten und Signale befinden sich in separaten Kategorien oder XML-Nodes. Lerne für jede dieser Kategorien, wie sie im Godot-Quellcode funktionieren, und fülle ihre <Beschreibung> aus.

Unsere Aufgabe ist es, den fehlenden Text zwischen diesen Markierungen zu ergänzen:

  • <description></description>
  • <brief_description></brief_description>
  • <constant></constant>
  • <method></method>
  • <member></member>
  • <signal></signal>

Schreiben Sie in einer klaren und einfachen Sprache. Befolgen Sie immer die folgenden Anweisungen Schreibrichtlinien, um Ihre Beschreibungen kurz und leicht lesbar zu halten. Lassen Sie keine leeren Zeilen in den Beschreibungen: Jede Zeile in der XML-Datei führt zu einem neuen Absatz.

So sieht eine Klasse in XML aus:

<class name="Node2D" inherits="CanvasItem" category="Core">
    <brief_description>
        Base node for 2D system.
    </brief_description>
    <description>
        Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
    </description>
    <methods>
        <method name="set_pos">
            <argument index="0" name="pos" type="Vector2">
            </argument>
            <description>
                Sets the position of the 2D node.
            </description>
        </method>
        [...]
        <method name="edit_set_pivot">
            <argument index="0" name="arg0" type="Vector2">
            </argument>
            <description>
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
        </member>
        [...]
        <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
        </member>
    </members>
    <constants>
    </constants>
</class>

Verwendn Sie einen Code-Editor wie Vim, Atom, Code, Notepad++ oder etwas ähnliches, um die Datei schnell zu bearbeiten. Benutze die Suchfunktion, um Klassen schnell zu finden.

Verbessern Sie die Formatierung mit BBCode-Tags

Godots Klassenreferenz unterstützt BBCode-ähnliche Tags. Sie fügen dem Text eine schöne Formatierung hinzu. Hier ist die Liste der verfügbaren Tags:

Tag Effekt Nutzung Ergebnis
[Class] eine Klasse verlinken bewege das [Sprite] bewege das Sprite
[method methodname] Link zu einer Methode in dieser Klasse Rufe [method hide] auf. Siehe hide.
[method Class.methodname] Link zur Methode einer anderen Klasse Rufe [method Spatial.hide] auf. Siehe hide.
[member membername] Link zu einem Mitglied in dieser Klasse Rufe [member scale] ab. Hole scale.
[member Class.membername] Link zum Mitglied einer anderen Klasse Rufe [member Node2D.scale] ab. Hole scale.
[signal signalname] Link zu einem Signal in dieser Klasse Sende [signal renamed]. Sende renamed.
[signal Class.signalname] Link zum Signal einer anderen Klasse Sende [signal Node.renamed]. Sende renamed.
[b] [/b] Fett Ein [b]fetter[/b] Text. Ein fetter Text.
[i] [/i] kursiv Ein [i]kursiver[/i] Text. Ein kursiver Text.
[code] [/code] Monospace Ein [code]monospace[/code] Text. Ein monospace Text.
[kbd] [/kbd] Tastatur/Maus Kürzel Eine [kbd]Ctrl + C[/kbd] Taste. Eine Ctrl + C Taste.
[codeblock] [/codeblock] Mehrzeiliger vorformatierter Block siehe unten siehe unten

Verwenden Sie [Codeblock] für vorformatierte Codeblöcke. Verwenden Sie in [Codeblock] immer vier Leerzeichen zum Einrücken (der Parser löscht Tabulatoren). Beispiel:

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

Wird angezeigt als:

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

Um wichtige Informationen zu kennzeichnen, füge am Ende der Beschreibung einen Absatz hinzu, der mit "[b]Note:[/b]" beginnt:

[b]Note:[/b] Only available when using the GLES2 renderer.

Um wichtige Informationen zu kennzeichnen, die zu Sicherheitsproblemen oder Datenverlust führen können, wenn sie nicht sorgfältig beachtet werden, füge am Ende der Beschreibung einen Absatz hinzu, der mit "[b]Warning:[/b]" beginnt:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

Füge für veraltete Eigenschaften einen Absatz hinzu, der mit "[i]Deprecated.[/i]" beginnt. Beachte die Verwendung von Kursivschrift anstelle von Fettdruck:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

Stelle in allen oben beschriebenen Abschnitten sicher, dass die Interpunktion aus Gründen der Konsistenz Teil der BBCode-Tags ist.

Ich weiß nicht, was diese Methode macht!

Kein Problem. Lassen Sie es hinter sich und listen Sie die Methoden auf, die Sie übersprungen haben, als Sie einen Abruf Ihrer Änderungen anforderten. Ein anderer Schreiber wird sich darum kümmern.

Sie können sich immer noch die Implementierung der Methoden im Godot-Quellcode auf GitHub ansehen. Wenn Sie Zweifel haben, können Sie auch auf der Frage-und-Antwort-Website <https://godotengine.org/qa/> __ und im IRC (freenode, #godotengine) nachfragen.

Lokalisierung

Die Dokumentation kann in eine beliebige Sprache auf Weblate übersetzt werden.

Übersetzte Zeichenfolgen werden manuell von Dokumentationsbetreuern im Repository godot-docs-l10n synchronisiert.

Sprachen mit einem guten Abschluss haben ihre eigenen lokalisierten Instanzen von ReadTheDocs. Öffnen Sie ein Problem im Repository godot-docs-l10n, wenn Sie der Meinung sind, dass eine neue Sprache vollständig genug ist, um eine eigene Instanz zu erhalten.