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:
Clona el repositorio godot-docs.
Instalar Sphinx
Para crear la documentación como archivos HTML, instala el readthedocs.org theme.
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.