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

Примечание

Добавление документации для GDExtensions возможно только для Godot 4.3 и более поздних версий. Поддержку можно интегрировать в ваш проект в любом случае, поскольку фрагмент кода проверит, используете ли вы подходящую версию godot-cpp. Если установить compatibility_minimum равным 4.2 и загрузить проект с расширением через редактор 4.2, страница документации для этого класса будет пустой. Само расширение продолжит работать.

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

Примечание

Мы предполагаем, что вы используете файлы проекта, описанные в example project со следующей структурой:

gdextension_cpp_example/  # GDExtension directory
|
+--demo/                  # game example/demo to test the extension
|   |
|   +--main.tscn
|   |
|   +--bin/
|       |
|       +--gdexample.gdextension
|
+--godot-cpp/             # C++ bindings
|
+--src/                   # source code of the extension we are building
|   |
|   +--register_types.cpp
|   +--register_types.h
|   +--gdexample.cpp
|   +--gdexample.h

Внутри каталога демонстрационного проекта Godot в каталоге GDExtension выполните следующую команду терминала:

# 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. Добавление ../ позволяет Godot определить местоположение файла SConstruct для GDExtension. Вызывая эту команду, Godot создаёт каталог doc_classes внутри каталога проекта, в котором генерирует XML-файлы для классов GDExtension. Эти файлы затем можно редактировать, добавляя информацию о переменных-членах, методах, сигналах и т. д.

Чтобы добавить отредактированную документацию в GDExtension и разрешить редактору загрузить ее, вам необходимо добавить следующие строки в файл SConstruct:

if env["target"] in ["editor", "template_debug"]:
    try:
        doc_data = env.GodotCPPDocData("src/gen/doc_data.gen.cpp", source=Glob("doc_classes/*.xml"))
        sources.append(doc_data)
    except AttributeError:
        print("Not including class reference as we're targeting a pre-4.3 baseline.")

Оператор if проверяет, компилируется ли библиотека GDExtension с флагами editor и template_debug. Затем SCons пытается загрузить все XML-файлы из каталога doc_classes и добавляет их в переменную sources, которая уже содержит все исходные файлы вашего расширения. Если это не удаётся, это означает, что мы пытаемся скомпилировать библиотеку, в то время как godot_cpp установлена на версию ниже 4.3.

После загрузки расширения в редактор Godot 4.3 или более поздней версии и открытия документации вашего класса расширения либо сочетанием клавиш Ctrl + Click в редакторе скриптов, либо в диалоговом окне справки редактора, вы увидите что-то вроде этого:

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

Оформление документации

Для оформления отдельных фрагментов текста можно использовать теги BBCode, аналогично тому, как они используются в RichTextLabels. Вы можете сделать текст жирным, курсивным, подчёркнутым, цветным, добавить блоки кода и т. д., встроив их в теги следующим образом:

[b]this text will be shown as bold[/b]

Currently, the supported tags for the GDExtension documentation system are:

Тег	Пример
b Заставляет `{text}` использовать жирный (или жирный курсив) шрифт `RichTextLabel`.	`[b]{text}[/b]`
i Заставляет `{text}` использовать курсив (или полужирный курсив) шрифта `RichTextLabel`.	`[i]{text}[/i]`
u Делает `{text}` подчеркнутым.	`[u]{text}[/u]`
s Делает `{text}` зачеркнутым.	`[s]{text}[/s]`
kbd Заставляет `{text}` использовать серый скошенный фон, указывая на сочетание клавиш.	`[kbd]{text}[/kbd]`
code Заставляет встроенный `{text}` использовать шрифт mono и задает цвет текста и фон как в коде.	`[code]{text}[/code]`
codeblocks Заставляет многострочный `{text}` использовать шрифт mono и стилизует цвет текста и фон как код. Добавление тега `[gdscript]` подчеркивает специфический синтаксис GDScript.	`[codeblocks]` `[gdscript]` `{text}` `[/gdscript]` `[/codeblocks]`
center Выравнивает `{text}` по горизонтали и центрирует. То же, что и `[p align=center]`.	`[center]{text}[/center]`
url Создаёт гиперссылку (подчёркнутый и интерактивный текст). Может содержать необязательный `{text}` или отображать `{link}` как есть.	`[url]{link}[/url]` `[url={link}]{text}[/url]`
img Вставляет изображение из `{path}` (может быть любой допустимый ресурс Texture2D). Если указано `{width}`, изображение попытается соответствовать этой ширине, сохраняя соотношение сторон. Если указаны оба параметра `{width}` и `{height}`, изображение будет масштабировано до этого размера. Добавьте `%` в конец значения `{width}` или `{height}`, чтобы указать его в процентах от ширины элемента управления, а не в пикселях. Если указана конфигурация `{valign}`, изображение попытается выровняться по окружающему тексту, см. Вертикальное выравнивание изображения и таблицы. Поддерживает параметры конфигурации, см. Image options.	`[img]{path}[/img]` `[img={width}]{path}[/img]` `[img={width}x{height}]{path}[/img]` `[img={valign}]{path}[/img]` `[img {options}]{path}[/img]`
color Изменяет цвет `{text}`. Цвет должен быть задан общим именем (см. Именованные цвета) или в HEX формате (например, `#ff00ff`, см. Шестнадцатеричные цветовые коды).	`[color={code/name}]{text}[/color]`

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

Возможно, вы захотите опубликовать онлайн-справочник по вашему 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. Вы можете использовать этот репозиторий в качестве основы для создания собственной системы документации. В следующем руководстве описаны основные этапы, но они не являются исчерпывающими: вам потребуется немного личного опыта, чтобы всё это заработало.

Добавьте godot-docs как подмодуль в папку docs/.
Скопируйте файлы conf.py, index.rst, .readthedocs.yaml в /docs/. Позже вы можете скопировать и отредактировать другие файлы godot-docs, например _templates/layout.html.
Измените эти файлы в соответствии с вашим проектом. Это в основном включает в себя изменение путей так, чтобы они указывали на подпапку godot-docs, а также добавление строк, указывающих на то, что вы собираете документацию именно для своего проекта, а не для Godot.
Создайте учётную запись на readthedocs.org. Импортируйте свой проект и измените базовый путь к файлу .readthedocs.yaml на /docs/.readthedocs.yaml.

После выполнения всех этих шагов ваша документация должна быть доступна по адресу <repo-name>.readthedocs.io.