Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Создание руководства с помощью Sphinx¶

На этой странице объясняется, как создать локальную копию руководства Godot с помощью движка Sphinx docs. Это позволяет вам иметь локальные HTML файлы и создавать документацию, например, в виде PDF, EPUB или LaTeX файла.

Before you get started, make sure that you have:

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

Примечание

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:
  py -m venv godot-docs-venv
  python3 -m venv godot-docs-venv
2. Activate the virtual environment:
  godot-docs-venv\Scripts\activate.bat
  source godot-docs-venv/bin/activate
3. (Optional) Update pre-installed packages:
  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
```
Примечание

On Windows, that command will run make.bat instead of GNU Make (or an alternative).

Кроме того, вы можете собрать документацию, запустив программу sphinx-build вручную:
```
sphinx-build -b html ./ _build/html
```

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

Затем вы можете просмотреть документацию, открыв _build/html/index.html в своем веб-браузере.

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.

Важно

Если вы удалите папку classes/, не используйте git add . при работе над запросом на пулл-реквест, иначе вся папка classes/ будет удалена при коммите. Более подробную информацию смотрите #3157 здесь.

Hints for performance¶

RAM usage¶

Сборка документации требует не менее 8 ГБ оперативной памяти для работы без подкачки дисков, что замедляет ее. Если у вас не менее 16 ГБ оперативной памяти, вы можете ускорить компиляцию, выполнив:

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