Contribuir a la Referencia de Clases

Nota

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.

Ver también

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

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

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

  • Crea un Fork del repositorio de Godot y clonalo
  • Mantén tu fork actualizado con otros colaboradores
  • Crea un Pull Request para que tus mejoras sean incluidas en los docs oficiales

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.

Crea un Fork de Godot

Crea un Fork propio de Godot Engine en un nuevo repositorio de Github.

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. It's also easier to clean up your repository if you run into any issues with Git.

git checkout -b your-new-branch-name

La nueva Branch es la misma que su Branch master hasta que empiece a escribir API docs. En el directorio doc/, encontrará la referencia de la clase.

Cómo mantener su copia local actualizada

Otros escritores contribuyen a la documentación de Godot. Tu repositorio local quedará atras de ellos, y tendrás que sincronizarlo. Específicamente si otro colaborador modifica la referencia de la clase mientras trabajas en la misma.

Primero crea un upstream remote con git para trabajar en el. Remotes son links para repositorios online desde los cuales puedes descargar los nuevos archivos.

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

Puedes verificar la lista de todos los servidores remotos con:

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

Este comando ira primeramente obtener, o descargará la última versión del repositorio de Godot. Luego, volverá a aplicar tus cambios locales por encima.

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

Atención El comando de arriba restablecerá su Branch al estado del Branch``upstream master``. Descartará todos los cambios locales, asegúrese de ejecutar este solamente antes de realizar cambios importantes.

Otra opción es eliminar el Branch en el cual estas trabajando, sincronizar el Branch master con el repositorio de Godot, y crear otro 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.

Actualizando plantilla de documentación

Cuando las clases son modificadas en el código fuente, el template de la documentación puede tornarse obsoleto. Para asegurarse de que esté editando una versión actualizada, debes compilar Godot (siguiendo la ref:doc_introduction_to_the_buildsystem referencia), y luego ejecutar el siguiente comando (asumiendo que estés utilizando Linux 64-bit):

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

Nota: Si esto fue realizado recientemente por otro colaborador, no necesitas seguir todos estos pasos (A menos que sepas que la clase que planeas editar haya sido modificada recientemente).

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.

En resumen: Si no sabes exactamente lo que haces, no alteres los archivos de GitHub.

Cómo editar una clase XML

Edita el archivo para la clase elegida en ``doc/classes/``para actualizar la referencia de la clase. El directorio tiene un archivo XML para cada clase. Este archivo XML lista todas las constantes y métodos de la referencia de la clase. Godot genera y actualiza los XMLs automáticamente.

Edita utilizando tu editor de textos preferido. Si usas un editor de código, asegurate de que este no altere el estilos de indentacion: Tabs para XML y 4 espacios dentro de los bloques BBcode. Más acerca de estos debajo.

Si necesitas verificar que las modificaciones que has hecho estan correctas en la documentación generada, compila Godot siguiendo ref:estos pasos <toc-devel-compiling>, ejecuta el editor y abre la página de ayuda para el material que hayas modificado.

Cómo escribir la referencia de la clase

Cada clase tiene una descripción larga y una corta. La descripción corta está siempre en el encabezado de la página, mientras que la descripción completa se encuentra debajo de la lista de los métodos, variables, constantes. Los metodos, variables del miembro, constantes y señales se encuentran separados por categorías o nodos de XML. Para cada uno, lee cómo funcionan en el código fuente de Godot, y completa su <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>

Escribe en un lenguaje simple y claro. Siempre siguiendo las pautas y orientaciones para mantener tus descripciones cortas y fácil de leer. No dejes lineas vacias en las descripciones: cada línea en el archivo XML resultará en un nuevo párrafo.

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

Utilice un editor de código como Vim, Atom, Code, Notepad++ or similar para editar el archivo rápidamente. Utilice la función de búsqueda para encontrar fácilmente las clases.

Mejorar el formato con etiquetas de estilo BBcode

Las referencias de las clases de Godot soportan tags BBcode. Estos permiten una buena formatación del texto. Sigue una lista de los tags disponibles:

Tag Efecto Uso Resultado
[Class] Enlazar a una clase Mover el [Sprite]. Move the Sprite.
[method methodname] Enlazar a un método de esta clase Llama [metodo hide]. Ver hide.
[método Clase.nombremetodo] Enlace al método de otra clase Llama [método Spatial.hide]. Ver hide.
[miembro nombremiembro] Enlazar a un miembro de esta clase Obtiene [miembro escala]. Get scale.
[miembro Clase.nombremiembro] 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.
[señal Clase.nombreseñal] Enlazar con la señal de otra clase Emit [signal Node.renamed]. Emit renamed.
[b] [/b] Negrita Un texto en [b]negrita[/b]. Algo de texto en negrita.
[i] [/i] Cursiva Un texto en [i]cursiva[/i]. Algo de texto en cursiva.
[code] [/code] Monospace Un texto [code]monoespaciado[/code]. Algo de texto monospace.
[kbd] [/kbd] Keyboard/mouse shortcut Alguna tecla [kbd]Ctrl + C[/kbd]. Some Ctrl + C key.
[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

La documentación se puede traducir en cualquier idioma en Hosted Weblate.

Los encargados de la documentación sincronizan las cadenas traducidas manualmente en el repositorio godot-docs-l10n.

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.