最近AkkaやAlpakkaなどのドキュメントで使われているLightbend製のParadoxというドキュメンテーションツールを試してみました。 *1
github.com
使い方はドキュメントを見ればわかると思いますが、要点だけまとめておきます。
はじめの一歩
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から参照するためのタグを埋め込んでおきます。
object HelloWorld extends App {
println("Hello World!")
}
ソースコードの引用機能を使うことでソースコードとドキュメント内のサンプルコードの二重管理を防ぐことができます。ドキュメントで使用できるということがテストケースを書くインセンティブになりますし、CIを回しておけばドキュメントに掲載されているコードはビルドが通るコードであることを保証できます。
その他の機能
Paradoxにはこの他にもドキュメント内のクロスリファレンスやScaladocへのリンクを簡単に張ることができたり、Java / Scalaなどソースコードをタブで切り替えられるような形で表示することもできます。シンプルながらフレームワークやライブラリなどのドキュメント用にツボを抑えたツールと言えるでしょう。
利用シーンは主にScalaに限定されますが、READMEだけでは使い方を書ききれなくなってきたらParadoxの利用を検討してみてもよいのではないかと思います。