Складання посібника зі Sphinx

На цій сторінці пояснюється, як створити локальну копію посібника Godot за допомогою механізму документів Sphinx. Це дозволяє мати локальні файли HTML і створювати документацію, наприклад, у форматі PDF, EPUB або LaTeX.

Перш ніж почати, переконайтеся, що у вас є:

Git
make (якщо ви не використовуєте Windows)
Python 3

Примітка

Python 3 має поставлятися з командою pip3. Можливо, вам доведеться написати python3 -m pip (Unix) або py -m pip (Windows) замість pip3. Якщо обидва підходи зазнають невдачі, переконайтеся, що у вас встановлено pip3.

(Необов’язково) Налаштувати віртуальне середовище. Віртуальні середовища запобігають потенційним конфліктам між пакетами Python у requirements.txt та іншими пакетами Python, встановленими у вашій системі.
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. (Необов’язково) Оновлення попередньо встановлених пакетів:
  py -m pip install --upgrade pip setuptools
  pip3 install --upgrade pip setuptools
Клонуйте репозиторій з документами:
```
git clone https://github.com/godotengine/godot-docs.git
```
Змініть каталог на сховище документів:
```
cd godot-docs
```
Встановіть необхідні пакунки:
```
pip3 install -r requirements.txt
```
Створюй документи:
```
make html
```
Примітка

У Windows ця команда запускатиме make.bat замість GNU Make (або альтернативи).

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

Компіляція займе деякий час, оскільки папка classes/ містить сотні файлів. Див. Підказки для виконання.

Потім ви можете переглядати документацію, відкривши _build/html/index.html у своєму веб-браузері.

Робота з помилками

Якщо ви зіткнетеся з помилками, ви можете спробувати таку команду:

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

Якщо ви отримуєте MemoryError або EOFError, ви можете видалити папку classes/ і знову запустити make. Це видалить посилання на класи з остаточної HTML-документації, але залишить решту без змін.

Важливо

Якщо ви видалите папку classes/, не використовуйте git add. під час роботи над запитом на отримання, інакше вся папка classes/ буде видалена під час фіксації. Див. #3157 для більш детальної інформації.

Підказки для виконання

використання оперативної пам'яті

Створення документації вимагає принаймні 8 ГБ оперативної пам’яті для роботи без підкачки диска, що уповільнює роботу. Якщо у вас принаймні 16 ГБ оперативної пам’яті, ви можете прискорити компіляцію, виконавши:

set SPHINXOPTS=-j2 && make html

make html SPHINXOPTS=-j2

Ви можете використовувати -j auto, щоб використовувати всі доступні потоки ЦП, але це може використовувати багато оперативної пам'яті, якщо у вас багато потоків ЦП. Наприклад, у системі з 32 потоками процесора -j auto (що тут відповідає -j 32) може вимагати 20+ ГБ оперативної пам’яті лише для Sphinx.

Зазначення списку файлів

Попередження

Цей розділ не працюватиме в Windows, оскільки репозиторій використовує спрощений сценарій make.bat замість справжньої програми GNU Make. Якщо ви хочете отримати термінал Linux у своїй системі, подумайте про використання Підсистеми Windows для Linux (WSL).

Ви можете вказати список файлів для створення, що може значно прискорити компіляцію:

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

Список файлів також можна надати командою git. Таким чином ви можете автоматично отримати назви всіх файлів, які були змінені з моменту останнього коміту (sed використовується, щоб розмістити їх в одному рядку).

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

Ви можете замінити HEAD на master, щоб повернути всі файли, змінені з гілки master:

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

Якщо будь-які зображення були змінені, вивід міститиме деякі попередження про них, але збірка триватиме правильно.