§Play 文档编写指南

Play 文档使用 Markdown 格式编写，代码示例从已编译、运行和测试的源文件提取。

编写 Play 文档时，必须遵守以下几项指南。

§性别中立语言和姓名

Play 社区尊重性别多样性。在文档中编写示例时，请尽可能使用性别中立语言和中性姓名。如果您不确定正确的措辞，请咨询您的审阅者。

§Markdown

所有 Markdown 文件必须在整个文档中具有唯一的名称，无论它们位于哪个文件夹中。Play 使用维基风格的链接和渲染文档。

段落中间的换行符被视为硬换行，类似于 GitHub 风格的 Markdown，并被渲染为换行符。因此，段落应包含在一行中。

§链接

指向文档中其他页面的链接应使用维基标记语法创建，例如

[[Optional description|ScalaRouting]]

图像也应使用上述语法。

注意：外部链接不应使用上述语法，而应使用标准 Markdown 链接语法。

§代码示例

所有支持的代码示例应从外部编译文件导入。执行此操作的语法为

@[some-label](code/SomeFeature.scala)

然后，该文件应使用#some-label分隔需要提取的行，例如

object SomeFeatureSpec extends Specification {
  "some feature" should {
    "do something" in {
      //#some-label
      val msg = Seq("Hello", "world").mkString(" ")
      //#some-label
      msg must_== "Hello world"
    }
  }
}

在上述情况下，val msg = ...行将被提取并作为代码渲染在页面中。所有代码示例应经过检查，以确保它们可以编译、运行，并且如果合理，则确保它们执行文档中所述的操作。它不应尝试测试功能本身。

所有 Scala/Java/路由/模板代码示例都在同一个类加载器上运行。因此，它们必须都具有良好的命名空间，位于与它们关联的文档部分相对应的包中。

在某些情况下，文档中应该出现的代码可能无法完全匹配根据上述指南可以编写的代码。特别是，一些代码示例需要使用诸如controllers之类的包名。作为最后的手段，如果没有任何其他方法可以解决此问题，您可以使用一些指令放在代码中，以指示代码示例提取器修改示例。这些是

###replace: foo — 将下一行替换为foo。您也可以选择用###终止此命令
###insert: foo — 在下一行之前插入foo。您也可以选择用###终止此命令
###skip — 跳过当前行
###skip: n — 跳过接下来的 n 行

例如

//#controller
// ###replace: package controllers
package foo.bar.controllers

import javax.inject.Inject
import play.api.mvc._

class HomeController @Inject()(cc:ControllerComponents)
 extends AbstractController(cc) {
  ...
}
//#controller

这些指令只能作为最后的手段使用，因为将代码示例提取到外部文件中的目的是，文档中的代码也会被编译和测试。指令会破坏这一点。

同样重要的是要了解代码示例的当前上下文，以确保记录了适当的导入语句。但是，在每个代码示例中都包含所有导入语句并不合理，因此必须谨慎行事。

下面是特定类型代码示例的指南。

§Scala

所有 Scala 代码示例都应该使用 specs 进行测试，并且如果可能，代码示例应该在 specs 中。鼓励在适当的地方使用局部类和方法定义。也鼓励在块中限定导入语句。

§Java

所有 Java 代码示例都应该使用 JUnit 进行测试。简单的代码示例通常很容易包含在 JUnit 测试中，但是当代码示例是方法或类时，就会变得更难。应该优先使用局部类和内部类，但这可能不可行，例如，静态方法只能出现在静态内部类上，但这意味着要向类添加静态修饰符，而如果它是外部类，则不会出现该修饰符。因此，在某些情况下，可能需要将 Java 代码示例提取到它们自己的文件中。

§Scala 模板

Scala 模板代码示例应该使用 Scala 中的 Specs 或 Java 中的 JUnit 进行测试。请注意，模板使用不同的默认导入进行编译，具体取决于它们位于 Scala 文档还是 Java 文档中。因此，在正确的上下文中测试它们也很重要。

尽可能将模板代码示例整合到单个文件中，但并非总是可行，例如，如果代码示例包含参数声明。

§路由文件

路由文件应使用 Scala 中的 Specs 或 Java 中的 JUnit 进行测试。路由文件应使用完整的包名命名，例如 scalaguide.http.routing.routes，以确保它们与其他路由代码示例隔离。

文档使用的路由编译器以特殊模式运行，该模式在该文件声明的命名空间内生成反向路由器。这意味着，尽管路由代码示例似乎使用对类的绝对引用，但实际上它是相对于路由器命名空间的。因此，在上面的路由文件中，如果您有一个名为 controllers.Application 的路由，它实际上将引用一个名为 scalaguide.http.routing.controllers.Application 的控制器。

§sbt 代码

sbt 代码示例应提取到 *.sbt 文件中。这些文件由 evaluateSbtFiles 任务单独测试，该任务编译并运行它们 - 通过加载，这意味着它运行设置定义（即，构建一个 Seq[Setting[_]]，但实际上不运行声明的任务或设置。用于运行这些文件的类加载器与 sbt 类加载器相同，因此代码片段所需的任何插件都需要是 sbt 项目的插件。

§其他代码

其他代码可能可测试也可能不可测试。使用 HTMLUnit 运行集成测试来测试 Javascript 代码可能是有意义的。加载配置以测试配置可能是有意义的。这里应该使用常识。

§测试文档

要构建文档，您首先需要在本地构建和发布 Play。您可以通过在 playframework 存储库的根目录中运行 sbt publishLocal 来完成此操作。

为了确保文档正确渲染，请在 documentation 目录中运行 sbt run。这将启动一个小型 Play 服务器，它只做一件事，就是提供文档。

为了确保代码示例可以编译、运行和测试通过，请运行 sbt test。

为了验证文档的结构是否健全，请运行 sbt validateDocs。这将检查是否存在损坏的维基链接、代码引用或资源链接，确保所有文档 Markdown 文件名都是唯一的，并确保不存在孤立页面。

下一步：翻译文档

发现此文档中的错误？此页面的源代码可以在此处找到。阅读完文档指南后，请随时贡献拉取请求。有疑问或建议要分享？前往我们的社区论坛与社区进行交流。