Додавання документації

Примітка

Додавання документації для 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 про те, де знаходиться файл GDExtension SConstruct. Викликаючи цю команду, 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]`
код Змушує вбудований `{text}` використовувати монофонічний шрифт і стилізує колір тексту та фон, як код.	`[code]{text}[/code]`
codeblocks Змушує багаторядковий `{text}` використовувати монофонічний шрифт і стилізує колір тексту та фон, як код. Додавання тегу `[gdscript]` підкреслює специфічний синтаксис GDScript.	`[codeblocks]` `[gdscript]` `{text}` `[/gdscript]` `[/codeblocks]`
центр Робить `{text}` горизонтально по центру. Те саме, що `[p align=center]`.	`[center]{text}[/center]`
адреса Створює гіперпосилання (підкреслений текст, який можна натиснути). Може містити необов’язковий `{text}` або відображати `{link}` як є.	`[url]{link}[/url]` `[url={link}]{text}[/url]`
img Вставляє зображення з `{path}` (може бути будь-яким дійсним ресурсом Texture2D). Якщо вказано `{width}`, зображення намагатиметься відповідати цій ширині, зберігаючи співвідношення сторін. Якщо надано і `{width}`, і `{height}`, зображення буде масштабовано до цього розміру. Додайте `%` до кінця значення `{width}` або `{height}`, щоб указати його у відсотках від ширини елемента керування замість пікселів. Якщо надається конфігурація `{valign}`, зображення спробує вирівняти навколишній текст, див. Вертикальне вирівнювання зображення та таблиці. Підтримує параметри конфігурації, див. Параметри зображення.	`[img]{шлях}[/img]` `[img={width}]{path}[/img]` `[img={width}x{height}]{path}[/img]` `[img={valign}]{path}[/img]` `[img {options}]{path}[/img]`
колір Змінює колір `{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.