Building the manual with Sphinx

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

Чтобы начать, вам необходимо:

  1. Clone the godot-docs repository.

  2. Установите Sphinx

  3. Чтобы собирать документы в виде HTML-файлов, установите тему readthedocs.org.

  4. Install the Sphinx extensions defined in the godot-docs repository requirements.txt file.

Мы рекомендуем использовать pip, менеджер пакетов Python для установки всех этих инструментов. Он поставляется с предустановленным Python. Убедитесь, что вы установили и используете Python 3. Вот команды для клонирования репозитория и последующей установки всех зависимостей.

Примечание

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.

git clone https://github.com/godotengine/godot-docs.git
pip3 install -r requirements.txt

Если программы установлены, вы можете собрать HTML-документацию из корневой папки этого хранилища с помощью следующей команды:

# On Linux and macOS
make html

# On Windows, you need to execute the ``make.bat`` file instead.
make.bat html

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

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

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

# On Linux/macOS
make html SPHINXOPTS=-j2

# On Windows
set SPHINXOPTS=-j2 && make html

Компиляция займет некоторое время, так как папка classes/ содержит сотни файлов.

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

В случае возникновения MemoryError или EOFError, вы можете удалить папку classes/ и запустить make снова. Это приведет к удалению ссылок на классы из конечной HTML-документации, но все остальное останется нетронутым.

Примечание

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

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

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

Сборка с помощью Sphinx и virtualenv

Если вы хотите, чтобы установка Sphinx была привязана к проекту, вы можете установить sphinx-build с помощью virtualenv. Для этого выполните эту команду из корневой папки этого репозитория:

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

Затем запустите make html, как показано выше.