§Play ドキュメント執筆ガイドライン

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

Play のドキュメントを書くときには忠実に従わなければならない、いくつかのガイドラインがあります。

§Markdown

すべての markdown ファイルは、それらがどのフォルダにあるかに依らず、ドキュメント全体に渡ってユニークな名前でなければなりません。Play は wiki スタイルのリンク方式を使用してドキュメントをレンダリングします。

GitHub flavored markdown と同様、段落途中の改行文字は強制折り返しと見なされ、改行としてレンダリングされます。このため、段落は単一行に含める必要があります。

§リンク

ドキュメント内の別ページへのリンクは、例えば以下のようにして 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 = ... が抽出され、コードとしてページ内にレンダリングされます。すべてのサンプルコードは、それらがコンパイル、実行できること、そして当然のことですが、それらがドキュメントに記述されているとおりに動作することを確認する必要があります。サンプルコードは、その機能をサンプルコード自身でテストすべきではありません。

すべてのサンプルコードは同一のクラスローダ上で実行されます。そのため、サンプルコードは関連するドキュメントの部分に該当するパッケージ内において、適切な名前空間に存在しなければなりません。

いくつかの場面では、上記のガイドラインに沿って書くことのできるコードを、ドキュメント内に表示されるコードと完全に一致させることができない場合があるかもしれません。特に、いくつかのコードサンプルは controllers のようなパッケージ名を使う必要があります。他に方法がない場合は最後の手段として、コードサンプル抽出機能にサンプルを変更するよう指示する、いくつかのディレクティブをコードに配置することができます。以下がそのディレクティブです:

###replace: foo - 次の行を foo で置き換えます。このコマンドを ### で終端することもできます
###insert: foo - 次の行の前に foo を挿入します。このコマンドを ### で終端することもできます
###skip - 現在の行をスキップします
###skip: n - 次の n 行をスキップします

例えば、以下のように使います:

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

import play.api.mvc._

object Application extends Controller {
  ...
}
//#controller

外部ファイルにコードサンプルを抽出することの要点は、ドキュメント中のすべてのコードがコンパイルされ、テストされていることなので、これらのディレクティブは最後の手段として使わなければなりません。ディレクティブはこの要点に違反します。

適切な import 文が記述されていることを保証するために、コードサンプルの現在のコンテキストに注意することも重要です。一方で、あらゆるコードサンプルに必ずしも import 文をすべて含める必要はないので、ここでは慎重さが示される必要があります。

特別な種類のコードサンプルに向けたガイドラインを以下に示します。

§Scala

すべての scala コードサンプルは specs を使ってテストする必要があり、そのコードサンプルは可能であれば spec の内部にあるべきです。適切な場所におけるローカルクラスおよびメソッド定義を推奨します。ブロック内にスコープを限定した import 文も推奨します。

§Java

すべての Java コードサンプルは JUnit を使ってテストする必要があります。通常、単純なコードサンプルは素直に JUnit テストの中に含めることができますが、コードサンプルがメソッドまたはクラスの場合、より難しくなります。ローカルなインナークラスを使う選択が見受けられるかもしれませんが、これが不可能な場合もあるかもしれません。例えば static メソッドは static インナークラス上にのみ登場するのですが、これは、もしそのクラスが外部クラスであったならば登場しないであろう static 修飾子をインナークラスに追加することを意味します。このため、いくつかの場合においては、Java コードサンプルをそのファイル自身に抽出する必要があるかもしれません。

§Scala テンプレート

Scala テンプレートコードサンプルは、Scala の Specs か Java の JUnit のいずれかでテストする必要があります。テンプレートは、Scala ドキュメントまたは Java ドキュメントのどちらに含まれるかによって、異なるデフォルトのインポートでコンパイルされることに注意してください。このため、正しいコンテキストにおいてテンプレートをテストすることも重要です。もしテンプレートが Java のスレッドローカルに依存しているならば、それは Java アクションからテストされるべきです。

可能であれば、テンプレートコードサンプルはひとつのファイルに統合されるべきですが、例えばコードサンプルが引数宣言を含む場合など、常に可能であるとは限らないでしょう。

§Routes ファイル

Routes ファイルは Scala の Specs か Java の JUnit のいずれかでテストする必要があります。Routes ファイルは、その他の routes コードサンプルと区別できることを保証するため、例えば scalaguide.http.routing.routes のように完全なパッケージ名を含めた名前にしなければなりません。

ドキュメントから利用される routes コンパイラは、そのドキュメントに宣言された名前空間内でリバースルータを生成する特別なモードで動作します。これは、routes コードサンプルは絶対パスを使ってクラスを参照しているように見えるにも関わらず、実際にはルーターの名前空間に対する相対パスを使うということを意味します。そのため、上記の routes ファイル内に controllers.Application というルートがある場合、これは実際には scalaguide.http.routing.controllers.Application というコントローラへの参照になります。

§SBT コード

SBT コードサンプルをコンパイルして実行するには、まったく異なるクラスローダとクラスパスを含む、とても作り込んだ SBT をセットアップする必要があるため、今のところ SBT コードサンプルをドキュメントの外に抽出することはできません。

§その他のコード

その他のコードはテストできないかもしれません。HTMLUnit を使った結合テストを実行することで Javascript コードをテストすることは理にかなっているかもしれません。実際にロードすることで設定ファイルをテストすることも意味があるでしょう。ここでは常識が用いられるべきです。

§ドキュメントをテストする

To build the docs, you’ll first need to build and publish Play locally. You can do this by running ./build publishLocal from within the framework directory of the playframework repository.
ドキュメントをビルドするには、まず Play をビルドしてローカルに publish する必要があります。これをするには、playframework リポジトリの framework ディレクトリで ./build publishLocal を実行します。

ドキュメントが正しくレンダリングされることを確認するには、 documentation ディレクトリ内で ./build run を実行します。これは、ドキュメントの提供以外は何もしない小さな Play サーバを開始します。

コードサンプルがコンパイル、実行され、そしてテストにパスすることを確認するには、./build test を実行します。

ドキュメントの構造が妥当であることを確認するには、./build validateDocs を実行します。このコマンドは、壊れた wiki リンクやコード参照、またはリソースリンクが存在しないことを確認し、ドキュメントの markdown ファイル名がユニークであることを保証し、そして孤立したページが存在しないことを保証します。

§外部 Play モジュールのコードサンプル

依存性の循環を避けるため、Play 本体に含まれない Play モジュールに関するあらゆるドキュメントは、そのコードサンプルを Play のその他のドキュメントと一緒に含めることができません。この問題に対処するため、これらモジュールのドキュメントは project/Build.scala 内の externalPlayModules マップのエントリに、そのモジュールのコードスニペットをビルドするために必要なその他の設定 (すなわち、ライブラリ依存性) と共に含めることができます。以下に例を示します:

val externalPlayModules: Map[String, Seq[Setting[_]]] = Map(
  "some-module" -> Seq(
    libraryDependencies += "com.example" %% "some-play-module" % "1.2.3" % "test"
  ),
  ...
)

ここで、このモジュールを使うコードスニペットをすべて code-some-module に配置します。これであらゆる SBT コマンドを実行することができます。モジュールが含まれていることを確認したら ./build -Dexternal.modules=some-module test を実行してみましょう。すべてのモジュールをテストするには ./build -Dexternal-modules=all test を実行します。

Next: 翻訳ガイドライン

このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。間違いを見つけた場合、このページのソースコードをここで確認することができます。ドキュメントガイドラインを読んで、お気軽にプルリクエストを送ってください。