Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

參與貢獻類別參照文件¶

:ref:`類參考 <doc_class_reference>`是一組描述引擎公開 API 的文章。這些文章中包括了對各種類、方法、屬性和全域物件的描述，可用於腳本的編寫。類參考可以從文件的側邊欄進入，線上閱讀，也可以在 Godot 編輯器中從説明功能表進入。

隨著引擎的發展以及功能的新增或修改，類參考的某些部分會變得過時，為此需要新增新的描述和範例。我們雖然鼓勵開發人員在提交拉取請求時，最好在類參考中記錄他們的所有工作，但我們不能期望每個人都能夠編寫高品質的文件，因此總是有需要像你這樣的貢獻者來完善現有的文件，建立缺失的參考資料。

如何撰寫類別參照文件¶

因為參考是包含在 Godot 編輯器中的，它的原始檔案是 `Godot 倉庫 <https://github.com/godotengine/godot>`_的一部分。我們是用 XML 檔來編寫的，所以貢獻類參考的流程和編寫線上手冊的流程有所不同。

警告

你 不應該\\直接編輯文件儲存庫 <https://github.com/godotengine/godot-docs/>_ 的 classes/ 資料夾中的 .rst 檔案。這些檔是自動生成的，並由專案維護人員手動同步。進一步閱讀以瞭解如何正確編輯類參考。

在主儲存庫中，類參考儲存在 XML 檔中，每個檔對應一個公開的類或全域物件。這些檔大部分位於 doc/classes/ 中，但某些模組也包含自己的文件。你將在 modules/<module_name>/doc_classes/ 目錄中找到它。要瞭解有關編輯 XML 檔的更多資訊，請參閱類別參照手冊。

也參考

有關詳細的 Git 使用方法與 PR 工作流程，請參考 Pull Request 工作流程一頁。該頁面中大部分關於 godotengine/godot 儲存庫的說明也適用於這個說明文件的儲存庫。

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

**重要：**如果你準備進行大量修改，就應該在 `godot-docs 倉庫 <https://github.com/godotengine/godot-docs/>`_中建立 Issue，或者在已有 Issue 上發表評論。這樣別人就會知道你準備處理某個類了。

參與貢獻的方法¶

開始貢獻的自然位置應當是你最熟悉的類。這確保了新增的描述將基於（你的）經驗和必要的專業知識，而不僅僅是方法或屬性的名稱。我們建議不要新增省事的描述，無論它看起來多麼有吸引力。這種描述掩蓋了對文件的需求，並且很難自動識別。

也參考

遵循這一原則非常重要，它使得我們能夠為貢獻者建立工具。例如類參考的完成狀態追蹤器。您可以使用它快速搜尋缺少描述的文件頁面。

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

You can still look at the methods' implementation in Godot's source code on GitHub. If you have doubts, feel free to ask on the Q&A website and Godot Contributors Chat.

警告

除非你只需要做一些微小的修改，比如修正一個拼寫錯誤，否則我們不建議你使用 GitHub 的網頁編輯器去編輯類參考文件的 XML。

而且，你也沒法在引擎中測試你的修改，也不能像 doc_class_reference_writing_guidelines_editing_xml 中描述的一樣使用校驗腳本。

修改引擎時更新類參考¶

當你建立了一個新的類或者修改了引擎原有的 API 時，就需要重新生成 doc/classes/ 中的 XML 檔。

為了達到這個目的，你首先需要編譯 Godot。方法請參閱建置系統簡介頁面。然後，在 Godot 根目錄中使用 --doctool 選項運作編譯出的 Godot 二進位檔案。例如，在 64 位 Linux 下，命令為：

./bin/godot.linuxbsd.editor.x86_64 --doctool

具體的後綴集可能不同。請仔細閱讀連結裡的文章以瞭解更多資訊。

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

請僅提交包含與您在 API 上的工作相關的更改。您可以使用 git checkout 來放棄對其他 XML 檔中的更改，但如果注意到不相關的檔案正在更新，請考慮一下再報告。理想情況下，運作此命令應該只提交您自己所做的更改。