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...

新增說明文件

備註

Adding documentation for GDExtensions is only possible with Godot 4.3 and later.

The GDExtension documentation system works in a similar manner to the built-in engine documentation: It uses XML files (one per class) to document the exposed constructors, properties, methods, constants, signals, and more.

To get started, identify your project's test project folder, which should contain a Godot project with your extension installed and working. If you are using godot-cpp-template, your GDExtension project already has a project folder. Alternatively, you can add one by following the steps described in 入門. Inside the project folder, run the following terminal command:

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

This command instructs Godot to generate documentation via the --doctool and --gdextension-docs commands. The ../ argument specifies the base path of your GDExtension.

After running this command, you should find XML files for your registered GDExtension classes inside the doc_classes folder in your GDExtension project. You could edit them now, but for this tutorial, the empty files will suffice.

Now that you have XML files containing your documentation, the next step is to include them in your GDExtension binary. Assuming you are using SCons as your build system, you can add the following lines to your SConstruct file. If you are using godot-cpp-template, your file already contains code for this.

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)

The if statement avoids adding the documentation to release builds of your GDExtension, where it is not needed. SCons then loads all the XML files inside the doc_classes directory, and appends the resulting targets to the sources array, to be included in your GDExtension build.

After building, launch your Godot project again. You can open the documentation of one of your extension classes either using Ctrl + Click on a class name in the script editor, or inside by finding it in the Editor help dialog. If everything went well, you should see something like this:

Writing and styling documentation

The format of the class reference XML files is the same as the one used by Godot. It is documented in 類別參考入門.

If you are looking for pointers to write high quality documentation, feel free to refer to Godot's documentation guidelines.

發佈說明文件至線上

你可能會想將自己的 GDExtension 文件線上發佈，像 Godot 官方網站那樣。最重要的一步是將 XML 格式的類別參考檔轉換成 reStructuredText（.rst）檔案：

# 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 uses Sphinx. You can use the repository as a basis to build your own documentation system. The following guide describes the basic steps, but they are not exhaustive: you will need a bit of personal insight to make it work.

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。