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

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

The format of the class reference XML files is the same as the one used by Godot. It is documented in Базовий буквар класу.

Якщо ви шукаєте поради щодо написання високоякісної документації, сміливо звертайтеся до керівних принципів документації» 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.

Після виконання всіх цих кроків ваша документація має бути доступною за адресою <repo-name>.readthedocs.io.