說明文件方針

本頁說明了當你想以撰寫或審閱說明文件、翻譯現有說明文件等形式參與貢獻 Godot Engine 時需要遵守的規則。另外,也請參考 godot-docs GitHub 儲存庫 的 README 與 說明文件首頁 以瞭解該遵守什麼規則以及如何聯絡說明文件團隊。

如何參與貢獻

建立與編輯說明文件頁面通常是在 godot-docs GitHub 儲存庫 中完成的。HTML (或 PDF 與 EPUB) 說明文件是由該儲存庫中的 .rst 檔 (reStructuredText 標記語言) 產生的。使用 PR (Pull Request) 修改這些頁面並合併後就會重建線上說明文件。

也參考

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

README.md 檔案包含了所有上手所需的資訊,請先閱讀。特別是 README.md 包含了一些技巧提示以及有關 reStructuredText 標記語言參照說明的連結。

警告

若想編輯 API 參照文件 ,請注意該文件 不應 在 godot-docs 儲存庫內編輯,而應編輯 Godot 主要儲存庫的 doc/classes/* XML 檔。這些檔案之後會用來產生編輯器內說明文件以及線上文件的 API 參照。更多詳情請參考 參與貢獻類別參照文件

怎麼樣算是好的說明文件?

說明文件應該以純英語撰寫,使用架構良好的句子,並以多個段落與子段落等級架構。說明文件應清楚明瞭並客觀。另外,也請參考 說明文件撰寫方針

我們通過下列定義區分教學頁與其他說明文件頁面:

  • 教學:主要用於說明有關編輯器或腳本的一個或多個主題的頁面,目標是要讓讀者達到特定的學習目標 (如「製作一個簡單的 2D 桌球遊戲」、「對物件施力」)。

  • 說明文件:用於精確描述某個概念,且應儘可能一次僅描述一個概念 (如 Sprite 類別的方法類別,或是 Godot 中輸入管理的概覽)。

只要遵守下列規則 (以及說明文件儲存庫中的規則),歡迎撰寫任何類型的說明文件。

標題

頁面應以頁面標題與 Sphinx 參照名稱開頭:

.. _doc_insert_your_title_here:

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

可以使用 :ref: 格式來以參照名稱連結到該頁面,如 :ref:`doc_insert_your_title_here` 會連結到上述範例頁面 (請注意參照中沒有最前面的底線)。

另外,也請避免使用美式駝峰法標題 (American CamelCase):標題的第一個單詞應首字母大寫,而接下來的單詞則不應首字母大寫。下列為正確範例:

  • Insert your title here

下列為錯誤範例:

  • Insert Your Title Here

只有專案、人名與節點類目名稱應首字母大寫。

翻譯現有頁面

可以在我們的 Hosted Weblate 上翻譯官方 Godot 說明文件。

Translation state

另外還有官方的 Godot i18n 儲存庫 ,可以在該儲存庫上看到上次同步資料是什麼時候。

授權條款

這份文件以及其包含的所有頁面都是以創用 CC—姓名標示 (CC-BY 3.0) 發表,作者請標示「Juan Linietsky, Ariel Manzur and the Godot community」。

一旦於該 GitHub 儲存庫中參與貢獻說明文件,你便同意以該授權條款發佈你所做出的修改。