Contruyendo el manual con Sphinx

Esta página explica como crear una copia local del manual de Godot usando el motor de documentos Sphinx. Esto te permite tener archivos locales HTML y crear la documentación como un archivo PDF, EPUB, o LaTeX, por ejemplo.

Antes de comenzar, asegúrate de tener:

Git
make (a menos que estés usando Windows)
Python 3

Nota

Python 3 should come with the pip3 command. You may need to write python3 -m pip (Unix) or py -m pip (Windows) instead of pip3. If both approaches fail, make sure that you have pip3 installed.

(Opcional) Establece un entorno virtual. Los entornos virtuales previenen posibles conflictos entre los paquetes de Python en requirements.txt y otros paquetes de Python que estén instalados en tu sistema.
1. Crea el entorno virtual:
  py -m venv godot-docs-venv
  python3 -m venv godot-docs-venv
2. Activa el entorno virtual:
  godot-docs-venv\Scripts\activate.bat
  source godot-docs-venv/bin/activate
3. (Opcional) Actualizar paquetes preinstalados:
  py -m pip install --upgrade pip setuptools
  pip3 install --upgrade pip setuptools

Clona el repositorio de documentación:

git clone https://github.com/godotengine/godot-docs.git

Cambiar directorio al repositorio de documentación:
```
cd godot-docs
```
Instala los paquetes requeridos:
```
pip3 install -r requirements.txt
```
Compila la documentación:
```
make html
```
Nota

En Windows, ese comando ejecutará make.bat en vez de GNU Make (o una alternativa).

Alternativamente, puedes construir la documentación ejecutando el programa sphinx-build manualmente:
```
sphinx-build -b html ./ _build/html
```

The compilation will take some time as the classes/ folder contains hundreds of files. See Hints for performance.

Luego puedes explorar la documentación abriendo _build/html/index.html en tu navegador web.

Dealing with errors

Si encuentras errores, puedes probar el siguiente comando:

make SPHINXBUILD=~/.local/bin/sphinx-build html

If you get a MemoryError or EOFError, you can remove the classes/ folder and run make again. This will drop the class references from the final HTML documentation, but will keep the rest intact.

Importante

Si eliminas la carpeta classes/, no uses git add . cuando trabajes en una solicitud de extracción (pull request), ya que toda la carpeta classes/ será eliminada cuando realices el commit. Consulta #3157 para más detalles al respecto.

Hints for performance

RAM usage

La construcción de la documentación requiere al menos 8 GB de RAM para ejecutarse sin intercambio de disco, lo que ralentiza el proceso. Si tienes al menos 16 GB de RAM, puedes acelerar la compilación ejecutando:

set SPHINXOPTS=-j2 && make html

make html SPHINXOPTS=-j2

Puedes usar -j auto para usar todos los hilos de CPU disponibles, pero esto puede usar mucha RAM si tienes muchos hilos de CPU. Por ejemplo, en un sistema con 32 hilos de CPU, -j auto (que corresponde a -j 32 aquí) puede requerir más de 20 GB de RAM solo para Sphinx.

Especificando una lista de archivos

Advertencia

This section will not work on Windows, since the repository is using a simplified make.bat script instead of the real GNU Make program. If you would like to get a Linux terminal on your system, consider using Windows Subsystem for Linux (WSL).

Puede especificar una lista de archivos para compilar, lo que puede acelerar enormemente la compilación:

make html FILELIST='classes/class_node.rst classes/class_resource.rst'

The list of files can also be provided by the git command. This way you can automatically get the names of all files that have changed since the last commit (sed is used to put them on the same line).

make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"

You can replace HEAD with master to return all files changed from the master branch:

make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"

If any images were modified, the output will contain some warnings about them, but the build will proceed correctly.