新增說明文件

備註

僅有 Godot 4.3 及之後的版本才能為 GDExtension 新增說明文件。不過你仍可將支援整合到專案中，因為該程式碼片段會檢查你是否使用了相容的 godot-cpp 版本。若你將 compatibility_minimum 設為 4.2，並透過 4.2 的編輯器載入含有該擴充的專案，該類別的說明文件頁面會是空白；擴充本身仍可正常運作。

GDExtension 的說明文件系統運作方式與內建引擎說明文件類似。它會為每個類別建立一份 XML 檔案，記錄該類別對外公開的建構子、屬性、方法、常數、訊號及主題項目。

備註

這裡假設你使用的是 範例專案 中說明的專案檔案結構：

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

在你的 GDExtension 專案的 Godot 範例目錄中，執行下列終端機指令：

# 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 的 SConstruct 檔案通常位於上一層，所以加上 ../。執行後，Godot 會在專案目錄內建立 doc_classes 資料夾，為所有 GDExtension 類別產生對應的 XML 檔案。這些檔案可進一步編輯，以補充成員變數、方法、訊號等資訊。

要讓 Godot 編輯器載入你補充過內容的說明文件，必須在 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.")

這段判斷式會檢查是否以 editor 以及 template_debug 編譯標誌來編譯 GDExtension 函式庫。SCons 會嘗試載入 doc_classes 目錄下所有 XML 檔案，並把它們加入到 sources 變數（這個變數已包含你的擴充原始檔）。如果載入失敗，就代表你目前使用的 godot_cpp 版本低於 4.3。

在 Godot 4.3 或更新版本的編輯器中載入該擴充套件後，可以在腳本編輯器中按 Ctrl + 點擊 類別名稱，或在編輯器說明視窗打開你的擴充類別說明頁面，就會看到類似下圖的內容：

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

說明文件樣式

要為說明文件的特定文字加上樣式，可以像 RichTextLabel 一樣使用 BBCode 標籤。你可以將文字設為粗體、斜體、底線、變色、程式碼區塊等，只要把文字包在如下標籤裡即可：

[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} 使用等寬字型，並套用程式碼專用的顏色與背景樣式。

[code]{text}[/code]
codeblocks
讓多行 {text} 使用等寬字型，並以程式碼樣式顯示文字顏色與背景。
若加上 [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} 設定，圖片會嘗試與周圍文字對齊，詳見 圖片與表格的垂直對齊。
支援更多設定選項，詳見 圖片選項。
[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 文件線上發佈，像 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 採用 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。