Building the manual with Sphinx¶
This page explains how to build a local copy of the Godot manual using the Sphinx docs engine. This allows you to have local HTML files and build the documentation as a PDF, EPUB, or LaTeX file, for example.
To get started, you need to:
Clone the godot-docs repository.
To build the docs as HTML files, install the readthedocs.org theme.
Install the Sphinx extensions defined in the godot-docs repository
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.
You may need to write
python3 -m pip (Unix) or
py -m pip (Windows) instead of
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
You can then browse the documentation by opening
your web browser.
In case you of a
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.
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
Alternatively, you can build the documentation by running the sphinx-build program manually:
sphinx-build -b html ./ _build
You can also specify a list of files to build, which can greatly speed up compilation:
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
make html as shown above.