最近AkkaやAlpakkaなどのドキュメントで使われているLightbend製のParadoxというドキュメンテーションツールを試してみました。 *1
使い方はドキュメントを見ればわかると思いますが、要点だけまとめておきます。
はじめの一歩
Paradoxはsbtプラグインとして実装されているのでまずはproject/plugins.sbtに以下を追記します。
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.2.12")
build.sbtに以下の設定を追加します。
enablePlugins(ParadoxPlugin)
paradoxTheme := Some(builtinParadoxTheme("generic"))
ドキュメントはsrc/main/paradoxディレクトリ配下に作成します。以下のような内容でindex.mdというファイルを作っておきます。
Paradoxのテスト
========
これはParadoxのテストページです。
ここまで設定したらsbt paradoxを実行するとtarget/paradox/site/mainディレクトリ配下にHTMLが生成されます。
ディレクティブを使ってみる
Paradoxでは基本的にMarkdownでドキュメントを記述しますが、@（インライン）、@@（ブロック）、@@@（コンテナ）で特殊なディレクティブを使用することができます。ここでは特に重要そうなディレクティブを2つだけ紹介しておきます。
サイドメニューを表示する
index.mdの末尾に以下のような記述を入れておくとサイドメニューを表示することができます。
@@@ index * [Getting started](getting-started.md) * [News](news.md) * [Documentation](documentation.md) * [Community](community.md) @@@
表示はこんな感じになります。
ソースコードを引用する
Paradoxの非常に便利な機能の1つがこのソースコードの引用機能です。以下のような記述でソースコードの一部を埋め込むことができます。
@@snip [Hello World](../../main/scala/HelloWorld.scala) { #sample }
ソースコードには以下のようにコメントでParadoxから参照するためのタグを埋め込んでおきます。
// #sample object HelloWorld extends App { println("Hello World!") } // #sample
ソースコードの引用機能を使うことでソースコードとドキュメント内のサンプルコードの二重管理を防ぐことができます。ドキュメントで使用できるということがテストケースを書くインセンティブになりますし、CIを回しておけばドキュメントに掲載されているコードはビルドが通るコードであることを保証できます。
その他の機能
Paradoxにはこの他にもドキュメント内のクロスリファレンスやScaladocへのリンクを簡単に張ることができたり、Java / Scalaなどソースコードをタブで切り替えられるような形で表示することもできます。シンプルながらフレームワークやライブラリなどのドキュメント用にツボを抑えたツールと言えるでしょう。
利用シーンは主にScalaに限定されますが、READMEだけでは使い方を書ききれなくなってきたらParadoxの利用を検討してみてもよいのではないかと思います。
*1:UnfilteredのWebサイトもParadoxを使っているそうです。sbt-siteとsbt-ghpagesを使ってGitHub Pagesにデプロイしているそう。
http://xuwei-k.hatenablog.com/entry/20161211/1481437560
