§Playドキュメント作成のガイドライン

Playのドキュメントは、コンパイル、実行、テストされたソースファイルから抽出されたコードサンプルとともに、Markdown形式で記述されています。

Playドキュメントを作成する際には、いくつかのガイドラインを遵守する必要があります。

§性別にとらわれない言語と名前

Playコミュニティは、性別の多様性を尊重しています。ドキュメントで例を記述する際は、可能な限り性別にとらわれない言語とユニセックスな名前を使用してください。適切な表現がわからない場合は、レビュアーに助けを求めてください。

§Markdown

すべてのmarkdownファイルは、どのフォルダにあるかに関わらず、ドキュメント全体で一意の名前を持つ必要があります。Playは、wikiスタイルのリンクとドキュメントのレンダリングを使用します。

段落の途中にある改行文字は、GitHubフレーバー付きmarkdownと同様に、強制改行とみなされ、改行としてレンダリングされます。したがって、段落は1行に収める必要があります。

§リンク

ドキュメント内の他のページへのリンクは、wikiマークアップ構文を使用して作成する必要があります。例：

[[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/routes/templatesコードサンプルは、同じクラスローダーで実行されます。したがって、それらはすべて、ドキュメントのどの部分に関連付けられているかに対応するパッケージ内で、適切に名前空間化されている必要があります。

場合によっては、上記のガイドラインに従って記述できるコードと、ドキュメントに表示されるコードが完全に一致しない場合があります。特に、一部のコードサンプルでは、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テストに含めるのが簡単ですが、コードサンプルがメソッドまたはクラスの場合、難しくなります。ローカルクラスと内部クラスの使用が推奨されますが、静的メソッドは静的な内部クラスにのみ表示でき、その場合、クラスにstatic修飾子を追加する必要があります。これは、外側のクラスの場合は表示されません。したがって、場合によっては、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を実行します。これにより、壊れたwikiリンク、コード参照、またはリソースリンクがないか、すべてのドキュメントmarkdownファイル名が一意であること、および孤立したページがないことがチェックされます。

次：ドキュメントの翻訳

このドキュメントにエラーを見つけましたか？このページのソースコードはこちらにあります。ドキュメントガイドラインをお読みいただいた上で、お気軽にプルリクエストをお送りください。質問や共有したいアドバイスはありますか？コミュニティフォーラムに参加して、コミュニティとの会話を始めましょう。