Building the manual with 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.

To get started, you need to:

  1. Clone the godot-docs repository.

  2. Instalar Sphinx

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

  4. Install the Sphinx extensions defined in the godot-docs repository requirements.txt file.

We recommend using pip, Python’s package manager to install all these tools. It comes pre-installed with Python. Ensure that you install and use Python 3. Here are the commands to clone the repository and then install all requirements.

Nota

You may need to write python3 -m pip (Unix) or py -m pip (Windows) instead of pip3. If both approaches fail, check that you have pip3 installed.

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

With the programs installed, you can build the HTML documentation from the root folder of this repository with the following command:

# On Linux and macOS
make html

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

If you run into errors, you may try the following command:

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

Building the documentation requires at least 8 GB of RAM to run without disk swapping, which slows it down. If you have at least 16 GB of RAM, you can speed up compilation by running:

# On Linux/macOS
make html SPHINXOPTS=-j2

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

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

You can then browse the documentation by opening _build/html/index.html in your web browser.

In case you of 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.

Nota

If you delete the classes/ folder, do not use git add . when working on a pull request or the whole classes/ folder will be removed when you commit. See #3157 for more detail.

Alternatively, you can build the documentation by running the sphinx-build program manually:

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

Building with Sphinx and virtualenv

If you want your Sphinx installation scoped to the project, you can install sphinx-build using virtualenv. To do so, run this command from this repository's root folder:

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

Then, run make html as shown above.