开发文档

SpongeDocs 是 Sponge 项目的官方文档。本文档旨在：

  • 帮助服主们建立他们自己的服务器。

  • 为有意向 Sponge 贡献代码的开发者指明方向。

  • 为开发者提供关于 Sponge 插件开发的相关信息。

报告问题

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

  1. 在 SpongeDocs 位于 GitHub 的问题追踪器 中反馈

  2. 在 论坛中的 SpongeDocs 版块 下发贴求助

  3. 你可以通过加入 IRC 频道 #spongedocs（位于 irc.esper.net） 联系我们（你需要先注册）

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

撰写文档

对 SpongeDocs 任何形式的变动都应当通过 SpongeDocs 位于 GitHub 的仓库 完成。我们并不期望你的 Pull Request 从一开始就是完美的，毕竟人无完人，金无足赤，绝大部分Pull Request也都会在复核时得到进一步完善；甚至我们还欢迎不完整的解释，所以——不要因为你有地方搞不明白而感到害怕；总会有人协助填补空白的。

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

全部 Sponge 文档均使用知识共享-署名-相同方式共享 4.0 国际许可协议（中文版）进行许可；所有艺术资源仍使用知识共享-署名-非商业性使用-禁止演绎 4.0 国际许可协议（中文版）进行许可。对本项目的贡献均视作同意将贡献内容按此授权许可发布。

文档规范指南

为确保所有 SpongeDocs 页面的排版一致性，我们在此规定了一套文档规范。随着文档的扩张，规范的内容也可能会有更新或变动。

  1. 标题应首字母大写（例如： Lorem Ipsum Dolor Sit Amet ），适用第八条的情况除外

  2. 应当使用有意义标题。（标题将会以链接形式出现）

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

  1. 尽量避免代码块中有大量文本注释，因为代码块不能被标记翻译。我们建议贡献者尽量避免代码块内的代码注释。简单的占位文本不受此建议影响。最理想的状态应该是：简练的代码示范，紧接着详细的解释。当然，不是所有的概念都能用几行代码解释清楚，所以还请量力而为。

  2. 在遇到特定类型的代码块时，应使用下列代码：

  • Groovy/Gradle 文件 -> groovy

  • HOCON 配置文件 -> guess（暂不支持 HOCON 语法高亮）

  • 游戏内或服务器终端命令 -> none

  • Java 代码 -> java

  • Json 格式的配置文件 -> json

  • Linux 终端命令 -> bash

  • 日志 -> none

  • 纯文本 -> text

  • Windows 命令行 -> bat

  1. 面向用户、插件开发者和 Sponge 开发者的内容应区别对待。

  2. 避免重复解释同一内容——请尽量使用超链接。

  3. 对于外部资料，请给出链接，不要直接复制。

  1. 对于翻译项目，会有些许例外。

  1. 区分 SpongeForge、SpongeVanilla 和 SpongeAPI。

  2. 若翻译后的文本在你的语言中看起来不通顺，你可以自行确立新的规则。

  3. Sponge 作为项目的名称，不应被翻译。

  1. 某些语言可选择使用译音。

  1. 我们强烈不建议使用诸如谷歌翻译之类的机翻工具。机翻往往有大量语义错误，通常也会被直接拒绝。

  2. 页标题和段落标题应以纯文本出现，不应出现纯文本块或其它形式的排版。

  3. 代码名应保持原样（例如作为实例字段（Field）存在的 blockState ，或是作为类名存在的 BlockState ，这两个就不能转写为 block state ）。同时，正文中的代码名应当以纯文本形式出现（例如， blockState ）。

  4. 每行最多120个字符。

  5. 导入应在文章中第一次需要导入的代码块中声明，此后毋需重复声明导入。

注解

有鉴于 Sponge 仍在不断变化，我们可以预见到 SpongeDocs 的编纂工作将陷入间歇性的低谷。可以肯定，在 Sponge 正式发布之前，很多资料将仍是空白。尽管如此，SpongeDocs 作为一个仍处于活跃状态的文档来说，仍然会有更新。在有生之年，它或许不会完美，但定将愈加完善。

我们随时欢迎各种贡献、建议及斧正。