Contributing to the class reference

Nota

Este guía esta disponible como un video tutorial en 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

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

  • 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

Deberias tener dos : origin, su fork en GitHub, que Git crea por defecto, y upstream, que acabas de añadir:

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

Si te sientes perdido, unete a nuestros Canales IRC <http://webchat.freenode.net/?channels=#godotengine> _ y pide ayuda. Usuarios experimentados en Git te darán una mano.

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 .

Los archivos XML en doc/clases deberian estar actualizados con las características actuales de Godot Engine. Puedes verificar que fue modificado utilizando el comando git diff. Si existen modificaciones en otras clases además de la que planeas documentar, por favor realiza un commit de estas modificaciones antes de empezar a editar el 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

Si bien puedes alterar los archivos en GitHub, no lo recomendamos. Dado que cientos de colaboradores trabajan en Godot, el histórial de Git debe permanecer limpio. Cada commit debe incluir todo lo relacionado a las mejoras que hayas realizado a la referencia de clases, nueva característica, bug fix, etc. Cuando editas desde GitHub, este creará un nuevo branch y un Pull Request cada vez que quieras guardarlos. Si pasan algunos pocos días antes de que tus modificaciones sean revisadas, no serás capaz de actualizar a la última versión del repositorio limpiamente. También, es más difícil mantener las indentaciones de Github limpias. Y estas son muy importantes para la documentación.

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.

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.

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>

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

Improve formatting with BBCode style tags

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 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] Atajo del teclado/ratón 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())

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.

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