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.

Para empezar, necesitas:

  1. Clona el repositorio godot-docs.

  2. Instalar Sphinx

  3. Para crear la documentación como archivos HTML, instala el readthedocs.org theme.

  4. Instala las extensiones de Sphinx definidas en el archivo requirements.txt del repositorio godot-docs.

Recomendamos usar pip, el gestor de paquetes de Python, para instalar todas estas herramientas. Viene preinstalado con Python. Asegúrate de instalar y usar Python 3. Aquí están los comandos para clonar el repositorio y luego instalar todos los requisitos.

Nota

Es posible que necesites escribir python3 -m pip (en Unix) o py -m pip (en Windows) en lugar de pip3. Si ambos enfoques fallan, verifica que tienes pip3 instalado.

git clone https://github.com/godotengine/godot-docs.git
pip3 install -r requirements.txt

Con los programas instalados, puedes construir la documentación en formato HTML desde la carpeta raíz de este repositorio con el siguiente comando:

# On Linux and macOS
make html

# On Windows, you need to execute the ``make.bat`` file instead.
make.bat html

Si encuentras errores, puedes probar el siguiente comando:

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

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:

# On Linux/macOS
make html SPHINXOPTS=-j2

# On Windows
set SPHINXOPTS=-j2 && make html

La compilación tomará un tiempo ya que la carpeta classes/ contiene cientos de archivos.

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

En caso de que ocurra un MemoryError o EOFError, puedes eliminar la carpeta classes/ y ejecutar nuevamente make. Esto eliminará las referencias de clases del documento HTML final pero mantendrá el resto intacto.

Nota

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.

Alternativamente, puedes construir la documentación ejecutando el programa sphinx-build manualmente:

sphinx-build -b html ./ _build

También puedes especificar una lista de archivos a compilar, lo que puede acelerar considerablemente la compilación:

sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst

Construyendo con Sphinx y virtualenv

Si deseas que tu instalación de Sphinx esté vinculada al proyecto, puedes instalar sphinx-build utilizando virtualenv. Para hacerlo, ejecuta este comando desde la carpeta raíz de este repositorio:

virtualenv --system-site-packages env/
. env/bin/activate
pip3 install -r requirements.txt

Luego, ejecuta make html como se muestra arriba.