Contribuyendo a la documentación

Esta guía explica cómo contribuir a la documentación de Godot, ya sea escribiendo o revisando páginas.

Ver también

Si deseas traducir páginas o la referencia de clases de inglés a otros idiomas, lee Localización del editor y de la documentación.

Primeros pasos

Para modificar o crear páginas en el manual de referencia, debes editar archivos .rst en el repositorio de GitHub de godot-docs. Al modificar esas páginas en una solicitud de extracción (pull request), se activa una reconstrucción de la documentación en línea al fusionarse.

Ver también

Para obtener detalles sobre el uso de Git y el flujo de trabajo de solicitudes de extracción (pull requests), consulta la página Flujo de trabajo para los Pull request. La mayoría de lo que describe sobre el repositorio principal godotengine/godot también es válido para el repositorio de documentación.

Advertencia

Los archivos fuente de la referencia de clases se encuentran en el repositorio del motor de Godot. Generamos la sección Godot API de esta documentación a partir de ellos. Si deseas actualizar la descripción de una clase, sus métodos o propiedades, lee la guía Contribuyendo a la referencia de la clase.

Qué es la documentación de Godot

La documentación de Godot tiene como objetivo ser un manual de referencia completo para el motor de juegos Godot. No está destinada a contener tutoriales paso a paso, excepto por dos tutoriales de creación de juegos en la sección de Introducción.

Nos esforzamos por escribir contenido factual en un lenguaje accesible y bien escrito. Para contribuir, también debes leer:

  1. Las pautas de escritura de la documentación. Allí encontrarás reglas y recomendaciones para escribir de manera que todos puedan entender.

  2. Las pautas de contenido. Explican los principios que seguimos para escribir la documentación y el tipo de contenido que aceptamos.

Contribuyendo con los cambios

Las solicitudes de extracción (Pull Requests) deben usar la rama master de forma predeterminada. Solo crea solicitudes de extracción en otras ramas (por ejemplo, 2.1 o 3.0) si tus cambios solo se aplican a esa versión específica de Godot.

Aunque sea menos conveniente de editar que una wiki, este repositorio Git es donde escribimos la documentación. Tener acceso directo a los archivos fuente en un sistema de control de versiones es una ventaja para asegurar la calidad de nuestra documentación.

Editando páginas existentes

Para editar una página existente, localiza su archivo fuente .rst y ábrelo en tu editor de texto favorito. Luego, puedes confirmar los cambios, subirlos a tu fork y hacer un pull request. Ten en cuenta que las páginas en classes/ no deben editarse aquí. Se generan automáticamente a partir de la referencia de clases XML de Godot. Consulta Contribuyendo a la referencia de la clase para más detalles.

Ver también

Para compilar el manual y probar los cambios en tu computadora, consulta Contruyendo el manual con Sphinx.

Editando páginas online

Puedes editar la documentación en línea haciendo clic en el enlace Editar en GitHub que se encuentra en la parte superior derecha de cada página.

Una vez allí, se abrirá el editor de texto de GitHub. Necesitas tener una cuenta en GitHub y haber iniciado sesión para poder utilizarlo. Una vez iniciada sesión, puedes proponer cambios de la siguiente manera:

  1. Haz clic en el botón "Editar en GitHub".

  2. En la página de GitHub a la que te llevará el enlace, haz clic en el ícono de lápiz que se encuentra en la esquina superior derecha, cerca de los botones Raw, Blame y Delete. El ícono de lápiz tiene una etiqueta emergente que dice "Fork this project and edit the file".

  3. Edita el texto en el editor de texto.

  4. En la parte inferior de la página web, resume los cambios que realizaste y haz clic en el botón Propose file change. Asegúrate de reemplazar el marcador de posición "Update file.rst" con una descripción breve pero clara de una línea, ya que esto será el título del commit.

  5. En las siguientes pantallas, haz clic en el botón Create pull request hasta que veas un mensaje como Username quiere fusionar 1 commit en godotengine:master desde Username:patch-1.

Otro colaborador revisará tus cambios y los fusionará en la documentación si son buenos. También pueden realizar cambios o pedirte que los hagas antes de fusionarlos.

Agregando nuevas páginas

Antes de agregar una nueva página, asegúrate de que se ajuste a la documentación existente:

  1. Busca en los problemas existentes o abre uno nuevo para ver si la página es necesaria.

  2. Asegúrate de que no haya una página que ya cubra el tema.

  3. Lea nuestro Directrices de contenido.

Para agregar una nueva página, crea un archivo .rst con un nombre significativo en la sección donde desees agregarlo, por ejemplo, tutorials/3d/light_baking.rst.

Luego, debes agregar tu página al "toctree" relevante (tabla de contenidos), por ejemplo, tutorials/3d/index.rst. Agrega el nombre de tu archivo nuevo en la lista en una nueva línea, usando una ruta relativa y sin extensión, por ejemplo, aquí light_baking.

Títulos

Siempre comienza las páginas con su título y un nombre de referencia de Sphinx:

.. _doc_insert_your_title_here:

Insert your title here
======================

La referencia _doc_insert_your_title_here y el título deben coincidir.

La referencia permite vincular a esta página utilizando el formato :ref:, por ejemplo, :ref:`doc_insert_your_title_here` enlazaría a la página de ejemplo anterior (nota la falta de guión bajo al principio de la referencia).

Escribe tus títulos como frases simples, sin capitalizar cada palabra:

  • Bueno: Entendiendo las señales en Godot

  • Malo: Entendiendo Señales En Godot

Solo los nombres propios, proyectos, personas y nombres de clases de nodos deben tener su primera letra en mayúscula.

Sintaxis de Sphinx y reStructuredText

Puedes consultar la Introducción a reST de Sphinx y la referencia oficial para obtener más detalles sobre la sintaxis.

Sphinx utiliza comentarios específicos de reST para realizar operaciones específicas, como definir la tabla de contenido (.. toctree::) o crear referencias cruzadas entre páginas. Para obtener más detalles, consulta la documentación oficial de Sphinx. Si deseas aprender cómo usar directivas de Sphinx como .. note:: o .. seealso::, puedes revisar la documentación de directivas de Sphinx.

Añadiendo imágenes y archivos adjuntos

Para agregar imágenes, colócalas en una carpeta img/ junto al archivo .rst con un nombre significativo e inclúyelas en tu página con:

.. image:: img/image_name.png

De manera similar, puedes incluir archivos adjuntos, como activos de soporte para un tutorial, colocándolos en una carpeta files/ junto al archivo .rst, y utilizando esta sintaxis en línea:

:download:`myfilename.zip <files/myfilename.zip>`

Licencia

Esta documentación y todas las páginas que contiene están publicadas bajo los términos de la licencia Creative Commons Attribution 3.0 (CC-BY 3.0), con atribución a "Juan Linietsky, Ariel Manzur y la comunidad Godot".

Al contribuir a la documentación en el repositorio de GitHub, aceptas que tus cambios se distribuyen bajo esta licencia.