貢獻說明文件

本指南說明如何貢獻 Godot 的說明文件，無論是撰寫還是審查頁面。

也參考

如果你想將頁面或類別參考從英文翻譯為其他語言，請參閱 編輯器與說明文件本地化。

入門

要修改或新增參考手冊的頁面，需編輯 godot-docs GitHub 儲存庫 內的 .rst 檔案。透過拉取請求（Pull Request）修改這些頁面並合併後，系統會自動重建線上文件。

也參考

有關 Git 的使用方式與拉取請求（Pull Request）流程，請參考 Pull Request 工作流程 頁面。該頁面大部分說明內容也適用於文件儲存庫。

警告

類別參考的原始檔案位於 Godot 引擎儲存庫。我們會根據這些檔案產生本文件的 類別參考 章節。若你想更新類別、方法或屬性的描述，請參閱 貢獻類別參考文件。

什麼是 Godot 文件

Godot 文件旨在作為 Godot 遊戲引擎的完整參考手冊。除了「入門」章節中的兩個遊戲製作教學外，並不包含循序漸進的教學。

我們致力於用易讀且清晰的語言撰寫正確內容。參與貢獻前，請先閱讀：

  1. 文件撰寫方針，你可以在那裡找到讓內容易於理解的寫作規範與建議。

  2. 內容指引，說明我們撰寫文件時遵循的原則，以及哪些內容是我們接受的。

貢獻變更

拉取請求（Pull request）預設應使用 master 分支。 只有當你的變更只適用於特定 Godot 版本（如 3.6 或 4.2 ）時，才針對該分支提出拉取請求。當拉取請求合併到 master 後，維護者通常會再將其揀選（cherry-pick）到目前的穩定分支。

雖然這裡不像 Wiki 那麼方便編輯，但我們所有說明文件皆在這個 Git 儲存庫中撰寫。透過版本控制系統直接存取原始檔，有助於維護文件品質。

編輯現有頁面

要編輯現有頁面，請找到該頁面的 .rst 原始檔，並使用你喜歡的文字編輯器開啟。完成修改後提交（commit），推送至你的 fork，再建立拉取請求（Pull request）。 注意： ``classes/`` 目錄下的頁面不應在此直接編輯， 這些頁面會自動從 Godot 的 XML 類別參考 產生。詳情請參閱 貢獻類別參考文件。

也參考

若要在本機建構說明文件並測試修改，請參考 使用 Sphinx 建置手冊。

線上編輯頁面

你可以點擊每頁右上角的 Edit on GitHub 連結，直接線上編輯說明文件。

這樣會將你帶到 GitHub 的文字編輯器。你必須有 GitHub 帳號並登入才能使用。登入後，你可以依下列步驟提出修改：

  1. 點擊 Edit on GitHub 按鈕。

  2. 在跳轉後的 GitHub 頁面，請確認當前分支為 "master"。然後點擊靠近 Raw、Blame、Delete 按鈕的右上角鉛筆圖示，其工具提示為「Fork this project and edit the file」。

  3. 在文字編輯器中編輯內容。

  4. 點擊「Commit changes...」，簡要說明你所做的變更，並將預設的「Update file.rst」替換為簡短明確的單行敘述（作為提交標題）。最後點選 Propose changes。

  5. 在接下來的畫面，持續點選 Create pull request 按鈕，直到看到類似「Username wants to merge 1 commit into godotengine:master from Username:patch-1」的訊息。

備註

如果拉取請求中除了你自己的提交外還有其他提交，很可能是因為你的分支不是從 "master" 建立的。你需要將分支 rebase 到 "master"，或重新建立一個新分支。

其他貢獻者會審查你的變更，若內容沒問題將會合併到文件中。審查過程中，他們也可能直接修改或請你再作調整。

新增頁面

新增頁面前，請先確認內容適合現有說明文件：

  1. 請先搜尋 現有議題，或提出新議題，以確認該頁面是否有其必要性。

  2. 確定沒有其他頁面已涵蓋此主題。

  3. 請先閱讀 內容指引。

要新增頁面，請於欲新增的章節下創建具有意義名稱的 .rst 檔案，例如 tutorials/3d/light_baking.rst。

接著，請將你的頁面加入對應的「toctree」（目錄，例如 tutorials/3d/index.rst）。於目錄中以相對路徑（不加副檔名）新增一行，如 light_baking。

標題

頁面開頭應包含標題與 Sphinx 參照名稱：

.. _doc_insert_your_title_here:

Insert your title here
======================

參照名稱 _doc_insert_your_title_here 必須與標題相對應。

參照名稱可以用 :ref: 格式連結到此頁面，例如 :ref:`doc_insert_your_title_here` 會連結到上述範例頁面（注意參照時不需加開頭底線）。

標題請以一般句子形式書寫，不要每個字都大寫：

  • 範例（佳）：Understanding signals in Godot

  • 範例（不佳）：Understanding Signals In Godot

僅有專有名詞、專案、人名與節點類別名稱才需首字大寫。

Sphinx 與 reStructuredText 語法

語法詳情請參考 Sphinx 的 reST Primer 與`官方參考手冊 <https://docutils.sourceforge.net/rst.html>`__。

Sphinx 會使用特殊的 reST 標記來執行特定操作，例如定義目錄（.. toctree::）或交叉連結頁面。詳細說明請參考 Sphinx 官方文件。如需學習 .. note::、.. seealso:: 等指令的用法，請參閱 Sphinx 指令說明。

新增圖片與附件

要新增圖片，請將圖檔存放於 .rst 檔旁的 img/ 目錄，並使用有意義的檔名，再於頁面中這樣引用：

.. image:: img/image_name.webp

另外，你也可以使用 figure 指令，讓圖片有明顯邊框並可置中顯示。

.. figure:: img/image_name.webp
    :align: center

你也可以提供附件作為教學輔助素材，將其放在 .rst 檔旁的 files/ 資料夾，並透過以下方式引用：

:download:`file_name.zip <files/file_name.zip>`

建議將專案範本或素材包等支援檔案託管於 godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> 儲存庫。你可直接用一般連結標記，連到該儲存庫產生的壓縮檔：

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

授權條款

本說明文件及其所有頁面均以 創用 CC 姓名標示 3.0 授權（CC BY 3.0） 發布，並請標註作者為「Juan Linietsky, Ariel Manzur and the Godot community」。

當你在 GitHub 儲存庫貢獻說明文件時，即表示你同意這些變更將以此授權條款釋出。