Wspieranie Dokumentacji Klasy

Informacja

This guide also is available as a video tutorial on YouTube.

Godot ships with many nodes and singletons to help you develop your games. Each is a class, documented in the class reference. This reference is essential for anyone learning the engine: it is available both online and in the engine.

But it's incomplete. Some methods, variables and signals lack descriptions. Others changed with recent releases and need updates. The developers can't write the entire reference on their own. Godot needs you, and all of us, to contribute.

Important: If you are planning to make larger changes or a more substantial contribution, it is usually a good idea to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too.

Zobacz także

Not sure where to start contributing? Take a look at the current class reference completion status here.

Jak wspierać projekt

The class reference lies in the following XML files, in Godot's GitHub repository: doc/classes/.

There are 5 steps to update the class reference (full guide below):

  1. Sforkuj repozytorium Godota
  2. Sklonuj repozytorium na swój komputer
  3. Edit the class file in doc/classes/ to write documentation
  4. Commit your changes and push them to your fork
  5. T

Ostrzeżenie

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.

Zacznij pracować z GitHubem

If you're new to Git and GitHub, this guide will help you get started. You'll learn to:

  • Forkować i klonować repozytorium Godota
  • Posiadać wraz z innymi aktualną wersję forka
  • Zrób pull request, by twoje zmiany znalazły się w oficjalnej dokumentacji

Informacja

If you're new to Git, the version control system Godot uses, go through GitHub's interactive guide. You'll learn some essential vocabulary and get a sense for the tool.

Fork Godota

Sforkuj Godot Engine z repozytorium GitHuba na własne potrzeby.

Sklonuj repozytorium na twój komputer:

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

Create a new branch to make your changes. It makes it a lot easier to sync your improvements with other docs writers. It's also easier to clean up your repository if you run into any issues with Git.

git checkout -b your-new-branch-name

The new branch is the same as your master branch, until you start to write API docs. In the doc/ folder, you'll find the class reference.

Jak utrzymać własny klon aktualnym

Other writers contribute to Godot's documentation. Your local repository will fall behind it, and you'll have to synchronize it. Especially if other contributors update the class reference while you work on it.

First add an upstream git remote to work with. Remotes are links to online repositories you can download new files from.

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

Możesz sprawdzić listę wszystkich zdalnych serwerów z:

git remote -v

You should have two: origin, your fork on GitHub that Git adds by default, and upstream, that you just added:

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)

Each time you want to sync your branch to the state of the upstream repository, enter:

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.

Jeśli wprowadziłeś zmiany, których nie chcesz zatrzymać w swoim lokalnym branchu, skorzystaj z poniższych komend:

git fetch upstream
git reset --hard upstream master

Uwaga: Powyższa komenda spowoduje zresetowanie twojego brancha do stanu upstream master brancha. Usunie to wszystkie lokalne zmiany. Upewnij się, że używasz jej wyłącznie przed przeprowadzeniem ważnych modyfikacji.

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.

Aktualizacja szablonu dokumentacji

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 Wstęp do systemu budowania 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"

Jesteś teraz gotowy do edycji tego pliku i dodania różnych rzeczy.

Uwaga! Jeśli to zostało zrobione przez innego członka społeczności, nie musisz wykonywać tych kroków (chyba, że wiesz, że klasa, którą chciałeś edytować została zmieniona niedawno).

Wyślij i poproś o wprowadzenie twoich zmian

Po zakończeniu wprowadzania zmian należy je przenieść do repozytorium GitHub:

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

Kiedy to nastąpi, możesz poprosić o Pull Request za pośrednictwem interfejsu GitHub w twoim forku Godota.

Ostrzeżenie

Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.

TL;DR: Jeśli nie wiesz, co dokładnie robisz, nie edytuj plików prosto z GitHuba.

Jak edytować klasę XML

Edytuj plik dla wybranej klasy w doc/classes/, aby zaktualizować odniesienie do klasy. Folder zawiera plik XML dla każdej klasy. XML zawiera listę stałych i metod, które można znaleźć w referencji klasy. Program Godot automatycznie generuje i aktualizuje XML.

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.

Jak napisać odniesienie do klasy

Każda klasa ma krótki i długi opis. Krótki opis znajduje się zawsze na górze strony, natomiast pełny opis znajduje się poniżej listy metod, zmiennych i stałych. Funkcje, zmienne, stałe i sygnały są w oddzielnych kategoriach lub węzłach XML. Dowiedz się, jak działają w kodzie źródłowym Godota i wypełnij ich <opis>.

Naszym zadaniem jest dodanie brakującego tekstu pomiędzy tymi znakami:

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

Napisz to w prostym i zrozumiałym języku. Zawsze postępuj zgodnie z pisanie poradników, aby Twoje opisy były krótkie i łatwe do przeczytania. Nie zostawiaj pustych wierszy w opisach: każdy wiersz w pliku XML stworzy nowy akapit.

Tak wygląda klasa w 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>

Użyj edytora kodu, takiego jak Vim, Atom, Code, Notepad++ lub innego podobnego narzędzia, aby szybko edytować plik. Użyj funkcji wyszukiwania, aby szybko znaleźć szukaną klasę.

Ulepszenie formatowania dzięki znacznikom w stylu BBcode

Godot's Class reference obsługuje znaczniki podobne do kodu BBcode. Dodają one do tekstu ładne formatowanie. Oto lista dostępnych znaczników:

Tag Efekt Użycie Wynik
[Klasa] Połączenie klasy Porusz [Sprite]. Porusz Sprite.
[method methodname] Połącz do funkcji w tej klasie Call [method hide]. See hide.
[method Class.methodname] Połącz z inną metodą klasy Call [method Spatial.hide]. See 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] Połączenie z sygnałem z innej klasy Emit [signal Node.renamed]. Emit renamed.
[b] [/b] Pogrubienie Tutaj [b]pogrubiony[/b] tekst. Tutaj pogrubiony tekst.
[i] [/i] Kursywa Tutaj [i]pochylony[/i] tekst. Tutaj pochylony tekst.
[code] [/code] Monospace Some [code]monospace[/code] text. Some monospace text.
[kbd] [/kbd] Keyboard/mouse shortcut Some [kbd]Ctrl + C[/kbd] key. Some Ctrl + C key.
[codeblock] [/codeblock] Wieloliniowy niesformatowany blok Zobacz poniżej. Zobacz poniżej.

Use [codeblock] for pre-formatted code blocks. Inside [codeblock], always use four spaces for indentation (the parser will delete tabs). Example:

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

Wyświetli się jako:

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

Nie wiem co te metody robią!

Nie ma problemu. Zostaw to i listę metod, które pominąłeś, kiedy tworzyłeś pull request dla wprowadzanych zmian. Inny twórca dokumentacji się tym zajmie.

Możesz także spojrzeć na to, jak implementowane są metody w kodzie źródłowym Godot umieszczonym na GitHubie. Dodatkowo, jeśli masz jakieś wątpliwości, to zapraszamy do zadawania pytań na Q&A website oraz na IRC (freenode, #godotengine).

Lokalizacja

Dokumentacja może być tłumaczona na każdy język na Hosted Weblate.

Translated strings are synced manually by documentation maintainers in the godot-docs-l10n repository.

Wersje językowe, które są już w dużej części skończone, mają swoje zakładki w ReadTheDocs. Możesz założyć issue w repozytorium godot-docs-l10n jeśli uważasz, że nowy język jest wystarczająco gotowy, by mieć stworzoną własną zakładkę.