Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0
. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
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.
Before you get started, make sure that you have:
Note
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.
(Optional) Set up a virtual environment. Virtual environments prevent potential conflicts between the Python packages in
requirements.txt
and other Python packages that are installed on your system.Create the virtual environment:
On Windows, run
py -m venv godot-docs-venv
On other platforms, run
python3 -m venv godot-docs-venv
Activate the virtual environment:
On Windows, run
godot-docs-venv\Scripts\activate.bat
On other platforms, run
source godot-docs-venv/bin/activate
(Optional) Update pre-installed packages:
On Windows, run
py -m pip install --upgrade pip setuptools
On other platforms, run
pip3 install --upgrade pip setuptools
Clone the docs repo:
git clone https://github.com/godotengine/godot-docs.git
Change directory into the docs repo:
cd godot-docs
Install the required packages:
pip3 install -r requirements.txt
Build the docs:
make html
Note
On Windows, that command will run make.bat
instead of GNU Make (or
an alternative).
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.
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.
Note
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
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