Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Добавление документации

Примечание

Добавление документации для GDExtensions возможно только в Godot 4.3 и новее.

Система документирования GDExtension работает аналогично встроенной документации движка: она использует XML-файлы (по одному на класс) для документирования представленных конструкторов, свойств, методов, констант, сигналов и т. д.

Для начала определите папку тестового проекта, которая должна содержать проект Godot с установленным и работающим расширением. Если вы используете godot-cpp-template, то в вашем проекте GDExtension уже есть папка project. В качестве альтернативы вы можете добавить её, выполнив шаги, описанные в Начало работы. Внутри папки project выполните следующую команду в терминале:

# Replace "godot" with the full path to a Godot editor binary
# if Godot is not installed in your `PATH`.
godot --doctool ../ --gdextension-docs

Эта команда указывает Godot сгенерировать документацию с помощью команд --doctool и --gdextension-docs. Аргумент ../ указывает базовый путь вашего GDExtension.

После выполнения этой команды вы должны найти XML-файлы для зарегистрированных классов GDExtension в папке doc_classes вашего проекта GDExtension. Вы можете отредактировать их сейчас, но для этого руководства пустые файлы подойдут.

Теперь, когда у вас есть XML-файлы с документацией, следующий шаг — включить их в ваш бинарный файл GDExtension. Предполагая, что вы используете SCons в качестве системы сборки, вы можете добавить следующие строки в файл SConstruct. Если вы используете godot-cpp-template, ваш файл уже содержит код для этого.

if env["target"] in ["editor", "template_debug"]:
    doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
    sources.append(doc_data)

Оператор if предотвращает добавление документации в релизные сборки вашего GDExtension, где она не нужна. Затем SCons загружает все XML-файлы в каталоге doc_classes и добавляет полученные цели в массив sources для включения в сборку GDExtension.

После сборки снова запустите проект Godot. Вы можете открыть документацию одного из классов расширения либо с помощью Ctrl + Click на имени класса в редакторе скриптов, либо найдя его в диалоге справки редактора. Если всё прошло хорошо, вы должны увидеть что-то вроде этого:

../../../_images/gdextension_docs_generation.webp

Написание и оформление документации

Формат XML-файлов справочника по классам такой же, как используется в Godot. Он описан в Справочник по классам.

Если вы ищете советы по написанию качественной документации, обратитесь к руководству по документации Godot.

Публикация документации онлайн

Возможно, вы захотите опубликовать онлайн-справочник по вашему GDExtension, аналогичный этому сайту. Самый важный шаг — создать файлы reStructuredText (.rst) на основе вашего XML-справочника классов:

# You need a version.py file, so download it first.
curl -sSLO https://raw.githubusercontent.com/godotengine/godot/refs/heads/master/version.py

# Edit version.py according to your project before proceeding.
# Then, run the rst generator. You'll need to have Python installed for this command to work.
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

Ваши файлы .rst теперь будут доступны в docs/classes/. Теперь вы можете использовать любой конструктор документации, поддерживающий синтаксис reStructuredText, чтобы создать на их основе веб-сайт.

godot-docs использует Sphinx. Вы можете использовать этот репозиторий как основу для создания собственной системы документации. В следующем руководстве описаны основные шаги, но они не являются исчерпывающими: вам потребуется немного личного опыта, чтобы всё заработало.

  1. Добавьте godot-docs как подмодуль в папку docs/.

  2. Скопируйте файлы conf.py, index.rst, .readthedocs.yaml в /docs/. Позже вы можете скопировать и отредактировать другие файлы godot-docs, например _templates/layout.html.

  3. Измените эти файлы в соответствии с вашим проектом. Это в основном включает в себя изменение путей так, чтобы они указывали на подпапку godot-docs, а также добавление строк, указывающих на то, что вы собираете документацию именно для своего проекта, а не для Godot.

  4. Создайте учётную запись на readthedocs.org. Импортируйте свой проект и измените базовый путь к файлу .readthedocs.yaml на /docs/.readthedocs.yaml.

Once you have completed all these steps, your documentation should be available at <repository-name>.readthedocs.io.