SpongeDocs 文件

警告

本文档是针对旧版 SpongeAPI 编写的，目前已不再维护。虽然相应的代码依然能在对应的 API 下工作，但相关政策、方针及链接可能有所变化。请在必要时参阅最新的文档获得相关信息。

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

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

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

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

回報問題

它可能總是出現：一個頁面過時，或有錯誤，或者你只是看著一個頁面，並認為「嗯，有一個更好的方式來解釋這個。」如果正是這樣，而且您卻無法自行解決問題，有三種方法可以讓我們意識到這個問題：

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

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

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

撰寫文件

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

本 Docs 是利用 reStructuredText（reST）編寫，如果你熟悉 Markdown（md），那麼 reST 的步驟不應該很難。如果您遇到問題，我們建議您加入我們的 論壇 或 Esper.net 的 #SpongeDocs 以尋求幫助。

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. 程式碼應該包含在 inline literals 或程式碼方塊中。

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

  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 作為一個仍處於活躍狀態的文件來說，仍然會有更新。在有生之年，它或許不會完美，但定將愈加完善。

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