SpongeDocs 文件
警告
本文档是针对旧版 SpongeAPI 编写的,目前已不再维护。虽然相应的代码依然能在对应的 API 下工作,但相关政策、方针及链接可能有所变化。请在必要时参阅最新的文档获得相关信息。
Sponge 文件也稱為「SpongeDocs」,是 Sponge 專案的官方文件。SpongeDocs 的目標是:
以基於 Sponge 的實作協助使用者建立自己的伺服器。
為開發人員提供有關如何對 Sponge 專案作出貢獻的資訊。
為開發人員提供有關如何著手插件開發的資訊。
回報問題
它可能總是出現:一個頁面過時,或有錯誤,或者你只是看著一個頁面,並認為「嗯,有一個更好的方式來解釋這個。」如果正是這樣,而且您卻無法自行解決問題,有三種方法可以讓我們意識到這個問題:
在 SpongeDocs 論壇版塊 建立一篇帖子
到 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 文件的指南。 隨著文件變大,此表單可能會添加(或者變形)。
標題應該遵循首字母大寫原則(Title Case,如:Headings Should Be Written in Title Case),是用第 8 項者除外。
頁面標題應該具有意義(標題顯示為超連結)。
程式碼應該包含在 inline literals 或程式碼方塊中。
盡量避免在程式碼區塊中放置太多的文字,因為它們不能被翻譯。不鼓勵貢獻者在程式碼區塊中加註。某些例子中可能必須用到簡單的佔位文字。理想情況下程式碼區塊的例子會很簡短,而正文中會對每個例子進行解釋。當然也有一些概念無法藉由用簡單的例子來說明。
為使用者、插件開發人員和 Sponge 開發人員區分各自的區域。
避免重複內容,盡可能共享頁面。
對於外部資源,請使用超連結,而不是直接複製。
有些例外是為了翻譯的目的。
要區分 SpongeForge、SpongeVanilla 和 SpongeAPI。
如果用你的語言看起來很糟糕,那就制定你自己的規則。
Sponge 是專案的標題,不應被翻譯。
某些語言也可能希望使用音譯。
強烈不鼓勵使用自動翻譯(如 Google 翻譯)。這些往往包含嚴重的錯誤,通常也會被直接拒絕。
頁面標題和章節標題應該是純文字,避免文字區塊或其他形式的排版。
程式碼符號應該保持原樣,並且沒有額外的空格(例如 blockState(一個欄位名稱)或 BlockState(一個類別名稱),而不是 block state)。它們也應該在正文中使用雙反引號(例如
blockState
)將其格式化。每行最多 120 字元。
導入(Import)應於每篇文章第一次需要時以程式碼區塊寫出,在此之後無須重複。
備註
有鑑於 Sponge 仍在不斷變化,我們可以預見到 SpongeDocs 的編纂工作將陷入間歇性的低谷。可以肯定,在 Sponge 正式發布之前,很多資料將仍是空白。儘管如此,SpongeDocs 作為一個仍處於活躍狀態的文件來說,仍然會有更新。在有生之年,它或許不會完美,但定將愈加完善。
隨時歡迎貢獻、建議和更正。