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