MarkdownベースのドキュメンテーションツールParadoxを使ってみた

Scala

最近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が生成されます。

f:id:takezoe:20170711160752p:plain

ディレクティブを使ってみる

Paradoxでは基本的にMarkdownでドキュメントを記述しますが、@（インライン）、@@（ブロック）、@@@（コンテナ）で特殊なディレクティブを使用することができます。ここでは特に重要そうなディレクティブを2つだけ紹介しておきます。

サイドメニューを表示する

index.mdの末尾に以下のような記述を入れておくとサイドメニューを表示することができます。

@@@ index

* [Getting started](getting-started.md)
* [News](news.md)
* [Documentation](documentation.md)
* [Community](community.md)

@@@

表示はこんな感じになります。

f:id:takezoe:20170711160839p:plain

ソースコードを引用する

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