參與貢獻類別參照文件

備註

本影片亦有 在 YouTube 上以影片教學的形式 提供。

Godot 提供了許多節點與單例來讓協助你開發遊戲。每個類別都在 類別參照文件 中提供說明文件。這份說明文件對於任何學習引擎的人來說都是不可或缺的:該文件可在線上以及引擎內取得。

但該參照文件並不完整。還缺少某些方法、變數與訊號的說明。而最近某些新版本的改動亦需要更新。開發人員無法自行撰寫整份參照文件。因此 Godot 需要你、以及我們全部的人來參與貢獻。

重要: 如果你有計劃要對程式碼做出較大的更改、或做出更多貢獻時,最好能建個 Issue (或在現有 Issue 上留言) 來讓其他人知道,避免有其他人也進行了同樣的工作。

也參考

不確定要從哪裡開始參與貢獻嗎?請看看 這裡 瞭解目前類別參照文件的完成度。

如何參與貢獻

類別參考文件以 XML 格式在 Godot 的 GitHub 儲存庫中下列位置提供:doc/classes/

要更新類別參照文件有 5 個步驟 (完整指南在後方):

  1. Fork Godot 的儲存庫

  2. Clone 你的 Fork 到電腦上

  3. 編輯 doc/classes/ 中的類別檔案,並撰寫完整說明文件

  4. 將更改 Commit,並 Push 回你的 Fork 上

  5. 在 Godot 儲存庫上開啟 PR (Pull Request)

警告

在編輯 API 參照文件時務必使用這些 XML 檔。請勿在 godot-docs 儲存庫的 線上說明文件中 編輯產生的 .rst 檔。

開始使用 GitHub

若你剛開始使用 Git 與 GitHub,本指南將協助你上手。你會學到:

  • Fork 並 Clone Godot 的儲存庫

  • 將你的 Fork 與其他貢獻者保持更新

  • 建立 PR (Pull Request) 來讓你改進的內容能顯現在官方說明文件中

備註

如果你是第一次使用 Git,也就是 Godot 使用的版本控制系統,請先參考 GitHub' 的互動式指南 (英語) 。在該指南中可以學會一些必要的單詞,並對該工具有個概念。

Fork Godot

將 Godot Engine Fork 到你自己的 GitHub 儲存庫中。

將儲存庫 Clone 到電腦上:

git clone https://github.com/your_name/godot.git

建立新的分支來處理改動。使用分支可以更輕鬆地將這些改進與其他說明文件作者同步。同時,使用分支也可以在遇到 Git 問題的時候更輕鬆地清理儲存庫。

git checkout -b your-new-branch-name

新建立的分支在開始撰寫 API 文件前都與 master 分支相同。在 doc/ 資料夾中可以找到類別參照文件。

如何將本機 Clone 保持更新

其他編寫者也會參與貢獻 Godot 的說明文件。Clone 到本機上的儲存庫會逐漸落後線上版本,並需要進行同步。尤其是當其他貢獻者在你編輯的這段期間內更新了類別參照文件時。

首先,先新增 upstream git remote 。「Remote」就像是指向線上儲存庫的連結,可以用來下載新檔案。

git remote add upstream https://github.com/godotengine/godot

可以通過下列指令來檢視所有 Remote 的列表:

git remote -v

該指令應該會顯示兩個 Remote:origin 為 GitHub 上的 Fork,由 Git 預設自動新增。另一個 upstream 則是我們剛才新增的:

origin  https://github.com/your_name/godot.git (fetch)
origin  https://github.com/your_name/godot.git (push)
upstream        https://github.com/godotengine/godot.git (fetch)
upstream        https://github.com/godotengine/godot.git (push)

每次要將分支的狀態與 Upstream 儲存庫同步時,請輸入:

git pull --rebase upstream master

該指令會先進行 fetch ,也就是下載最新版的 Godot 儲存庫。然後,Git 會將目前本機上的修改重新套用至儲存庫的最上方。

如果有作出修改但不想保留本機上的分支,則改用下列指令:

git fetch upstream
git reset --hard upstream master

警告: 上述指令會將目前分支的狀態重設為 upstream master 分支。使用該指令會取消所有本機上的更改。請只在 進行重要更改前 才執行該指令。

另一種方法是刪除目前正在處理的分支,並將 master 分支與 Godot 儲存庫同步,然後再建立新分支:

git checkout master
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name

如果不知道該怎麼做的話,請到我們的 IRC 頻道 上尋求幫助。有經驗的 Git 使用者會協助你。

更新說明文件樣板

當原始碼裡的類別被修改後,說明文件樣板就有可能過時。為了確保正在的是最新版本,請先編譯 Godot (可參考 建置系統簡介 一頁),然後執行下列指令 (假設為 64 位元 Linux):

./bin/godot.x11.tools.64 --doctool .

接著,doc/classes 內的 XML 應該會更新為目前 Godot Engine 功能的版本。可以使用 git diff 指令進行確認。如果改動包含了你目前計劃要編輯的說明文件以外的類別,則請先將這些改動 Commit,然後再開始編輯樣板:

git add doc/classes/*.xml
git commit -m "Sync classes reference template with current code base"

現在可以開始編輯這個檔案並新內容。

請注意: 若最近已經有其他貢獻者更新過,則並不需一定要執行這些步驟 (除非確定要編輯的類別最近 有被修改過)。

Push 做出的改動並開啟 PR

完成修改後,請將改動 Push 到 GitHub 儲存庫中:

git add doc/classes/<edited_file>.xml
git commit -m "Explain your modifications."
git push

完成後,便可通過 Godot Fork 上的 GitHub UI 來開啟 PR (Pull Request)。

警告

雖然也可以在 GitHub 上編輯檔案,但並不建議這麼做。由於有上百個貢獻者都參與了 Godot,因此必須確保有乾淨的 Git 歷史記錄。所有對類別參照文件的改進都應包含在同一個 Commit 內,包含新功能、Bug 修正…等。用 GitHub 編輯時,每次保存檔案都會建立新分支並開啟新 PR。如果過了幾天之後該更改才被審閱,則將無法乾淨利落地將分支更新到最新版本。另外,要用 GitHub 來保持整齊的縮排也很困難,而對於說明文件來說縮排很重要。

用一句話來說:如果你不確定自己在做什麼的話,就不要在 GitHub 上編輯檔案。

如果編輯類別 XML

請編輯 doc/classes/ 內所選類別的檔案來更新類別參照文件。該資料夾包含了用於各個類別的 XML 檔。這些 XML 中列出了可在類別參照文件中找到的常數與方法。Godot 會自動產生並更新 XML 檔。

使用慣用的編輯器開啟 XML 檔。若使用程式碼編輯器,請確保不要更改到縮排樣式:XML 使用 Tab 資源,BBCode 風格的區塊中則使用 4 個空格。詳情見下方說明。

若有需要確認在產生的文件中做出的修改是否正確,請依照 此處 的說明建置 Godot,然後執行編輯器並打開說明頁面檢視做出修改的頁面。

如何撰寫類別參照文件

各個類別都有一個簡短說明與長說明。簡短說明位於頁面頂部,而完整的長說明則位於方法、變數與常數列表下方。方法、成員變數、常數與訊號都放在個別分類或不同 XML 節點內。請從 Godot 的原始碼中瞭解這些功能各自如何運作,並填寫相應的 <descrioption>。

我們的工作就是要填寫這些標籤內缺少的文字:

  • <description></description>

  • <brief_description></brief_description>

  • <constant></constant>

  • <method></method>

  • <member></member>

  • <signal></signal>

請以清晰明瞭的文字撰寫。務必遵守 撰寫方針 以保持說明簡短且容易閱讀。在簡介中 請不要保留空行 :在 XML 檔中每一行都會開新段落。

下列為類別在 XML 中的樣子:

<class name="Node2D" inherits="CanvasItem" category="Core">
    <brief_description>
        Base node for 2D system.
    </brief_description>
    <description>
        Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
    </description>
    <methods>
        <method name="set_pos">
            <argument index="0" name="pos" type="Vector2">
            </argument>
            <description>
                Sets the position of the 2D node.
            </description>
        </method>
        [...]
        <method name="edit_set_pivot">
            <argument index="0" name="arg0" type="Vector2">
            </argument>
            <description>
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
        </member>
        [...]
        <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
        </member>
    </members>
    <constants>
    </constants>
</class>

請使用 Vim, Atom, Code, Notepad++ 或其他類似的編輯器來快速編輯檔案。可使用搜尋功能來快速找到類別。

使用 BBCode 風格的標籤來增強格式

Godot 的類別參照文件支援類似 BBCode 的標籤。這些標籤可以為文字加上格式。下面列出了所有可用的標籤:

Tag

效果

使用量

結果

[Class]

類別連結

移動 [Sprite]。

移動 Sprite

[method 方法名稱]

該類別中方法的連結

呼叫 [method hide]。

參考 hide

[method 類別.方法名稱]

另一個類別的方法連結

呼叫 [method Spatial.hide]。

參考 hide

[member 成員名稱]

該類別中成員的連結

取得 [member scale]。

取得 scale

[member 類別.成員名稱]

另一個方法的成員連結

取得 [member Node2D.scale]。

取得 scale

[signal 訊號名稱]

該類別訊號的連結

發送 [signal renamed]。

發送 renamed

[signal 類別.訊號名稱]

另一個類別的訊號連結

發送 [signal Node.renamed]。

發送 renamed

[b] [/b]

粗體

普通的 [b]粗體[/b] 文字。

普通的 粗體 文字。

[i] [/i]

斜體

普通的 [i]斜體[/i] 文字。

普通的 斜體 文字。

[code] [/code]

等寬字體

普通的 [code]等寬字體 (Monospace)[/code] 文字。

普通的 等寬字體 (Monospace) 文字。

[kbd] [/kbd]

鍵盤或滑鼠快捷鍵

普通的 [kbd]Ctrl + C[/kbd] 按鍵。

普通的 Ctrl + C 按鍵。

[codeblock] [/codeblock]

多行預格式化區塊

參見下方。

參見下方。

使用 [codeblock] 來標記預先格式化的程式碼區塊。在 [codeblock] 中,請務必使用 四個空格 來進行縮排 (剖析器會移除 Tab 字元)。例如:

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

會顯示為:

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

若要標記出重要的資訊,可在說明最後新增以「[b]Note:[/b]」開頭的段落:

[b]Note:[/b] Only available when using the GLES2 renderer.

若要標記出未多加留意可能導致安全性問題或遺失資料的警示資訊,請在說明最後加上以「[b]Warning:[/b]」開頭的段落:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

而已停止維護的屬性,請加上以「[i]Deprecated.[/i]」開頭的段落。請注意,這裡使用的是斜體而非粗體:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

請注意,上面描述的所有段落中,標點符號都是 BBCode 標籤中的一部分,請保持一致性。

我不知道這個方法做了什麼!

沒關係,先跳過即可。並請在為更改開啟 PR 時列出所有跳過的方法。其他編寫者會處理這些方法。

也可以在 GitHub 上 Godot 的原始碼中看看該方法的實作。另外,如果有疑慮時,歡迎在 Q&A 網站 與 IRC (freenode, #godotengine) 上提問。

本地化

說明文件可以在 Hosted Weblate 上翻譯為任意語言。

翻譯字串是由說明文件維護人員手動同步到 godot-docs-l10n 儲存庫內。

有一定完成度的語言便會有自己的本地化 ReadTheDocs 實體。如果你認為有哪個語言的完成度夠高能開啟自己的實體時,請在 godot-docs-l10n 上開啟 Issue。