Building the manual with Sphinx
- Dealing with errors
- Hints for performance
  - RAM usage
  - Specifying a list of files

Up to date

This page is up to date for Godot 4.0. If you 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:

Git
make (unless you’re using Windows)
Python 3

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.
1. Create the virtual environment:
  
  WindowsOther platforms
```
py -m venv godot-docs-venv
```
```
python3 -m venv godot-docs-venv
```
2. Activate the virtual environment:
  
  WindowsOther platforms
```
godot-docs-venv\Scripts\activate.bat
```
```
source godot-docs-venv/bin/activate
```
3. (Optional) Update pre-installed packages:
  
  WindowsOther platforms
```
py -m pip install --upgrade pip setuptools
```
```
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).

Alternatively, you can build the documentation by running the sphinx-build program manually:
```
sphinx-build -b html ./ _build/html
```

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

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

Dealing with errors

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

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

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.

Important

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.

Hints for performance

RAM usage

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:

WindowsOther platforms

set SPHINXOPTS=-j2 && make html

make html SPHINXOPTS=-j2

You can use -j auto to use all available CPU threads, but this can use a lot of RAM if you have a lot of CPU threads. For instance, on a system with 32 CPU threads, -j auto (which corresponds to -j 32 here) can require 20+ GB of RAM for Sphinx alone.

Specifying a list of files

You can specify a list of files to build, which can greatly speed up compilation:

make FILELIST='classes/class_node.rst classes/class_resource.rst' html