Создание руководства с помощью 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. Создайте виртуальную среду:
  py -m venv godot-docs-venv
  python3 -m venv godot-docs-venv
2. Активируйте виртуальную среду:
  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
Клонируйте репозиторий документов:
```
git clone https://github.com/godotengine/godot-docs.git
```
Change directory into the docs repo:
```
cd godot-docs
```
Установите необходимые пакеты:
```
pip3 install -r requirements.txt
```
Создайте документы:
```
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

Предупреждение

This section will not work on Windows, since the repository is using a simplified make.bat script instead of the real GNU Make program. If you would like to get a Linux terminal on your system, consider using Windows Subsystem for Linux (WSL).

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

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

The list of files can also be provided by the git command. This way you can automatically get the names of all files that have changed since the last commit (sed is used to put them on the same line).

make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"

You can replace HEAD with master to return all files changed from the master branch:

make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"

If any images were modified, the output will contain some warnings about them, but the build will proceed correctly.