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:

  1. Clone the godot-docs repository.

  2. Install Sphinx

  3. To build the docs as HTML files, install the 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.

Note

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.

  1. git clone https://github.com/godotengine/godot-docs.git
  2. 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:

  1. # On Linux and MacOS
  2. make html
  4. # On Windows, you need to execute the ``make.bat`` file instead.
  5. make.bat html

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

  1. 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:

  1. # On Linux/macOS
  2. make html SPHINXOPTS=-j2
  4. # On Windows
  5. 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.

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:

  1. sphinx-build -b html ./ _build

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:

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

Then, run make html as shown above.