开发文档
警告
本文档是针对旧版 SpongeAPI 编写的,目前已不再维护。虽然相应的代码依然能在对应的 API 下工作,但相关政策、方针及链接可能有所变化。请在必要时参阅最新的文档获得相关信息。
SpongeDocs 是 Sponge 项目的官方文档。本文档旨在:
帮助服主们建立他们自己的服务器。
为有意向 Sponge 贡献代码的开发者指明方向。
为开发者提供关于 Sponge 插件开发的相关信息。
报告问题
然而,文档难免会有疏漏,诸如过期内容,或是错别字,抑或你觉得“某个地方这样说更好”。如果你遇到了这样的情况,但你因为种种原因无法直接为我们提供帮助,我们仍然留有三条反馈的途径:
在 论坛中的 SpongeDocs 版块 下发贴求助
你可以通过加入 IRC 频道 #spongedocs(位于 irc.esper.net) 联系我们(你需要先注册)
撰写文档
对 SpongeDocs 任何形式的变动都应当通过 SpongeDocs 位于 GitHub 的仓库 完成。我们并不期望你的 Pull Request 从一开始就是完美的,毕竟人无完人,金无足赤,绝大部分Pull Request也都会在复核时得到进一步完善;甚至我们还欢迎不完整的解释,所以——不要因为你有地方搞不明白而感到害怕;总会有人协助填补空白的。
SpongeDocs 使用 reStructuredText (reST) 标记语言写就,若是你在此之前熟悉 Markdown (md) 这样的文本标记语言, reST 对你来说将不会有太大困难。若遇到困难,我们建议你前往 论坛 或 我们在 Esper.net 上的 IRC 频道 #SpongeDocs 寻求帮助。
全部 Sponge 文档均使用知识共享-署名-相同方式共享 4.0 国际许可协议(中文版)进行许可;所有艺术资源仍使用知识共享-署名-非商业性使用-禁止演绎 4.0 国际许可协议(中文版)进行许可。对本项目的贡献均视作同意将贡献内容按此授权许可发布。
文档规范指南
为确保所有 SpongeDocs 页面的排版一致性,我们在此规定了一套文档规范。随着文档的扩张,规范的内容也可能会有更新或变动。
标题应首字母大写(例如: Lorem Ipsum Dolor Sit Amet ),适用第八条的情况除外
应当使用有意义标题。(标题将会以链接形式出现)
程序代码应以 行内纯文本 (inline literal) 的形式出现,或包含在代码块中。
尽量避免代码块中有大量文本注释,因为代码块不能被标记翻译。我们建议贡献者尽量避免代码块内的代码注释。简单的占位文本不受此建议影响。最理想的状态应该是:简练的代码示范,紧接着详细的解释。当然,不是所有的概念都能用几行代码解释清楚,所以还请量力而为。
面向用户、插件开发者和 Sponge 开发者的内容应区别对待。
避免重复解释同一内容——请尽量使用超链接。
对于外部资料,请给出链接,不要直接复制。
对于翻译项目,会有些许例外。
区分 SpongeForge、SpongeVanilla 和 SpongeAPI。
若翻译后的文本在你的语言中看起来不通顺,你可以自行确立新的规则。
Sponge 作为项目的名称,不应被翻译。
某些语言可选择使用译音。
我们强烈不建议使用诸如谷歌翻译之类的机翻工具。机翻往往有严重错误,通常也会被直接拒绝。
页标题和段落标题应以纯文本出现,不应出现纯文本块或其它形式的排版。
代码名应保持原样(例如作为实例字段(Field)存在的 blockState ,或是作为类名存在的 BlockState ,这两个就不能转写为 block state )。同时,正文中的代码名应当以纯文本形式出现(例如,
blockState
)。每行最多120个字符。
导入应在文章中第一次需要导入的代码块中声明,此后毋需重复声明导入。
注解
有鉴于 Sponge 仍在不断变化,我们可以预见到 SpongeDocs 的编纂工作将陷入间歇性的低谷。可以肯定,在 Sponge 正式发布之前,很多资料将仍是空白。尽管如此,SpongeDocs 作为一个仍处于活跃状态的文档来说,仍然会有更新。在有生之年,它或许不会完美,但定将愈加完善。
我们随时欢迎各种贡献、建议及斧正。