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. Clone your fork on your computer
  3. Edit the class file in doc/classes/ to write documentation
  4. Commit your changes and push them to your fork
  5. Make a pull request on the Godot repository

Warnung

Always use these XML files to edit the API reference. Do not edit the generated .rst files in the online documentation, hosted in the godot-docs repository.

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

This command will first fetch, or download the latest version of the Godot repository. Then, it will reapply your local changes on top.

If you made changes you don't want to keep in your local branch, use the following commands instead:

git fetch upstream
git reset --hard upstream master

Warning: The above command will reset your branch to the state of the upstream master branch. It will discard all local changes. Make sure to only run this before you make important changes.

Another option is to delete the branch you're working on, synchronize the master branch with the Godot repository, and create a new branch:

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

If you're feeling lost by now, come to our IRC channels and ask for help. Experienced Git users will give you a hand.

Updating the documentation template

When classes are modified in the source code, the documentation template might become outdated. To make sure that you are editing an up-to-date version, you first need to compile Godot (you can follow the Einführung in das Buildsystem page), and then run the following command (assuming 64-bit Linux):

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

The XML files in doc/classes should then be up-to-date with current Godot Engine features. You can then check what changed using the git diff command. If there are changes to other classes than the one you are planning to document, please commit those changes first before starting to edit the template:

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

You are now ready to edit this file to add stuff.

Note: If this has been done recently by another contributor, you don't forcefully need to go through these steps (unless you know that the class you plan to edit has been modified recently).

Push and request a pull of your changes

Once your modifications are finished, push your changes on your GitHub repository:

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

When it's done, you can ask for a Pull Request via the GitHub UI of your Godot fork.

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: If you don't know what you're doing exactly, do not edit files from GitHub.

How to edit class XML

Edit the file for your chosen class in doc/classes/ to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you'll find in the class reference. Godot generates and updates the XML automatically.

Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.

If you need to check that the modifications you've made are correct in the generated documentation, build Godot as described here, run the editor and open the help for the page you modified.

Wie man eine Klassenreferenz schreibt

Each class has a brief and a long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables and constants. Methods, member variables, constants and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their <description>.

Our job is to add the missing text between these marks:

  • <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.

Here's how a class looks like in XML:

<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>

Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast.

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 to a method in this class Call [method hide]. Siehe hide.
[method Class.methodname] Link to another class's method Call [method Spatial.hide]. Siehe hide.
[member membername] Link to a member in this class Get [member scale]. Get scale.
[member Class.membername] Link to another class's member Get [member Node2D.scale]. Get scale.
[signal signalname] Link to a signal in this class Emit [signal renamed]. Emit renamed.
[signal Class.signalname] Link to another class's signal Emit [signal Node.renamed]. Emit 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())

To denote important information, add a paragraph starting with "[b]Note:[/b]" at the end of the description:

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

To denote crucial information that could cause security issues or loss of data if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at the end of the description:

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

For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]". Notice the use of italics instead of bold:

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

In all the paragraphs described above, make sure the punctuation is part of the BBCode tags for consistency.

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.