SpongeDocs 文件

Sponge 文件也稱為「SpongeDocs」，是 Sponge 專案的官方文件。SpongeDocs 的目標是：

  • 以基於 Sponge 的實作協助使用者建立自己的伺服器。

  • 為開發人員提供有關如何對 Sponge 專案作出貢獻的資訊。

  • 為開發人員提供有關如何著手插件開發的資訊。

回報問題

然而，文档难免会有疏漏，诸如过期内容，或是错别字，抑或你觉得“某个地方这样说更好”。如果你遇到了这样的情况，但你因为种种原因无法直接为我们提供帮助，我们仍然留有四条反馈的途径：

  1. 在 SpongeDocs 的 GitHub 上建立一個 Issue

  2. 在 SpongeDocs 論壇版塊 建立一篇帖子

  3. 到 irc.esper.net 上的 #spongedocs 頻道訪問我們（需要註冊）

  4. 你可以在我们的 Discord 上找到我们，具体来说是 #docs 频道。

撰寫文件

若欲更改或添加 SpongeDocs，應以 Pull Request 提交給 GitHub 上的 SpongeDocs 儲存庫。我們並不要求它完美，因為在審查過程中會修改 Pull Request。我們也歡迎不完整的解釋，所以如果有一些你不明白的地方請別顧慮。總會有人能夠把空白補上。

SpongeDocs 使用 reStructuredText（reST）格式，如果你熟悉 Markdown（md），上手 reST 对你来说不会很难。如果你遇到了问题，我们建议你在 irc.esper.net 的 #spongedocs 频道 或我们的 Discord 服务器 的 #docs 上联系我们。这两个地方是互联的，所以选哪个都没有区别。此外，你还可以在我们的论坛上联系我们。

Sponge 文件是採用 Creative Commons - Share-Alike license 授權。 美術資產則是根據 Creative Commons - Non Commercial, No Derivatives license 。所有貢獻者皆預設同意該授權協議。

樣式指南

為了確保我們在所有的 SpongeDocs 頁面中都有一致的格式，下面是我們編寫 Sponge 文件的指南。 隨著文件變大，此表單可能會添加（或者變形）。

  1. 標題應該遵循首字母大寫原則（Title Case，如：Headings Should Be Written in Title Case），是用第 8 項者除外。

  2. 頁面標題應該具有意義（標題顯示為超連結）。

  3. 代码应该使用引号包裹，或放置于代码块中

  1. 盡量避免在程式碼區塊中放置太多的文字，因為它們不能被翻譯。不鼓勵貢獻者在程式碼區塊中加註。某些例子中可能必須用到簡單的佔位文字。理想情況下程式碼區塊的例子會很簡短，而正文中會對每個例子進行解釋。當然也有一些概念無法藉由用簡單的例子來說明。

  2. 對特定程式碼區塊使用以下程式碼區塊類型：

  • Groovy/Gradle 檔案 -> groovy

  • Hocon 設定檔 -> guess （hocon 高亮尚未被支援）

  • 遊戲中/伺服器 Console 指令 -> none

  • Java 程式碼 -> java

  • Json 設定檔 -> json

  • Linux 終端機 -> bash

  • Logs -> none

  • 文本 -> text

  • Windows-Console -> bat

  1. 為使用者、插件開發人員和 Sponge 開發人員區分各自的區域。

  2. 避免重複內容，盡可能共享頁面。

  3. 對於外部資源，請使用超連結，而不是直接複製。

  1. 有些例外是為了翻譯的目的。

  1. 要區分 SpongeForge、SpongeVanilla 和 SpongeAPI。

  2. 如果用你的語言看起來很糟糕，那就制定你自己的規則。

  3. Sponge 是專案的標題，不應被翻譯。

  1. 某些語言也可能希望使用音譯。

  1. 強烈不鼓勵使用自動翻譯（如 Google 翻譯）。這些往往包含嚴重的錯誤，通常也會被直接拒絕。

  2. 頁面標題和章節標題應該是純文字，避免文字區塊或其他形式的排版。

  3. 程式碼符號應該保持原樣，並且沒有額外的空格（例如 blockState（一個欄位名稱）或 BlockState（一個類別名稱），而不是 block state）。它們也應該在正文中使用雙反引號（例如 blockState ）將其格式化。

  4. 每行最多 120 字元。

  5. 導入（Import）應於每篇文章第一次需要時以程式碼區塊寫出，在此之後無須重複。

備註

有鑑於 Sponge 仍在不斷變化，我們可以預見到 SpongeDocs 的編纂工作將陷入間歇性的低谷。可以肯定，在 Sponge 正式發布之前，很多資料將仍是空白。儘管如此，SpongeDocs 作為一個仍處於活躍狀態的文件來說，仍然會有更新。在有生之年，它或許不會完美，但定將愈加完善。

隨時歡迎貢獻、建議和更正。