Contribuir a la Referencia de Clases

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.

Nota

This guide is available as a video tutorial on YouTube.

How to contribute

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

Advertencia

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.

Comenzar con GitHub

Si eres nuevo en git y GitHub, esta guía te ayudará a empezar. Aprenderás a hacerlo:

  • Fork and clone Godot’s repository
  • Keep your fork up to date with other contributors
  • Create a pull request so your improvements end in the official docs

Nota

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 Godot

Fork the Godot Engine into a GitHub repository of your own.

Clonar el repositorio en tu computadora:

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, and it’s easier to cleanup your repository clean if you have 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.

How to keep your local clone up-to-date

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

You can check the list of all remote servers with:

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)

Cada vez que quieras sincronizar tu rama con el estado del repositorio upstream, introduce:

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.

Si has hecho cambios que no quieres mantener en tu rama local, usa en su lugar los siguientes comandos:

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

Actualización de la plantilla de documentación

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 Introduction to the 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"

Ahora estás listo para editar este archivo y añadir cosas.

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

Solicitar push o pull de sus cambios

Una vez que se hayan terminado las modificaciones, haz un push de los cambios en el repositorio de GitHub:

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

Cuando este listo, puedes hacer un Pull Request a través de la UI de GitHub de tu fork de Godot.

Advertencia

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

Cómo editar una clase 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 favourite 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.

Cómo escribir la referencia de la clase

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

Nuestro trabajo es añadir el texto que falta entre estas marcas:

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

Write in a clear and simple language. Always follow the writing guidelines to keep your descriptions short and easy to read. Do not leave empty lines in the descriptions: each line in the XML file will result in a new paragraph.

Así es como se ve una clase en 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>
            Set 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.

Mejorar el formato con etiquetas de estilo BBcode

Godot’s class reference supports BBcode-like tags. They add nice formatting to the text. Here’s the list of available tags:

Tag Efecto Uso Resultado
[Class] Enlazar a una clase Move the [Sprite]. Move the class_sprite.
[method methodname] Enlazar a un método de esta clase Call [method hide]. Ver hide.
[method Class.methodname] Link to another class’s method Call [method Spatial.hide]. Ver hide.
[member membername] Enlazar a un miembro de esta clase Get [member scale]. Get scale.
[member Class.membername] Enlazar a otro miembro de la clase Get [member Node2D.scale]. Get scale.
[signal nombresignal] Enlazar con una señal de esta clase Emit [signal renamed]. Emit renamed.
[signal Class.signalname] Link to another class’s signal Emit [signal Node.renamed]. Emit renamed.
[b] [/b] Negrita Some [b]bold[/b] text. Algo de texto en negrita.
[i] [/i] Cursiva Some [i]italic[/i] text. Algo de texto en cursiva.
[code] [/code] Monospace Some [code]monospace[/code] text. Algo de texto monospace.
[codeblock] [/codeblock] Bloque pre-formateado con múltiples líneas Ver a continuación. Ver a continuación.

Usa [bloque de código] para pre-formatear bloques de código. Dentro de [bloque de código], usa cuatro espacios para hacer sangría (el analizador eliminará las tabulaciones). Por ejemplo:

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

Se mostrará como:

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

¡No sé que hace este método!

No hay problema. Déjalo atrás, y enumera los métodos que omitiste cuando solicitaste un pull de tus cambios. Otro redactor se encargará de ello.

Aún puedes echar un vistazo a la implementación de los métodos en el código fuente de Godot en Github . También, si tienes alguna duda, siéntete libre de preguntar en el apartado web Preguntas y Respuestas y en el IRC (freenode, #godotengine).

Traducciones

The documentation can be translated in any language on Hosted Weblate.

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

Los lenguajes con un buen nivel de completación tienen sus propias instancias localizadas de ReadTheDocs. Abre un issue en el repositorio godot-docs-l10n si crees que un nuevo idioma es lo suficientemente completo como para obtener su propia instancia.