lightbend/paradoxとsbt-site, sbt-ghpages使ってunfilteredのwebsite新しくした

unfiltered scala pamflet paradox travis-ci

http://unfiltered.ws



これはScalaアドベントカレンダー2016、アドベンター版の11日目です。

http://www.adventar.org/calendars/1492

少し前にコミッターになった、と書きましたが、その後色々やったわけですが、全部書くと長くなりそうなのでひとまずドキュメントの件についてだけ書く。


そもそもの動機や前提として

  • しばらく放置されていたので、色々と古い非推奨や消えたメソッド使ってる箇所がある
  • そもそもコンパイル時チェックないので、最初から間違ってる箇所もある
  • 原作者(n8han)のwebsite http://unfiltered.databinder.net/Unfiltered.html に手動デプロイ?な運用だったらしいが、そもそも今回原作者が全然メンテしなくなったことにより、groupIdまで変えてプロジェクトを複数の新しいコミッターが引き継いだ感じなので、ドキュメントのデプロイ方法から考える必要がある
  • 現在はpamflet https://github.com/foundweekends/pamflet というの使ってる。これも原作者同じ(n8han)であり、eed3si9nさんが引き継いだ新しいorganizationに移管されて、一応開発続いてなくもないがそれほど活発じゃない

というわけでissueたてる

https://github.com/unfiltered/unfiltered/issues/353


みたいな状況なわけです(それを簡単に上記issueに書いた)。


sbt-pamfletがコンパイルチェック出来るの知らなかったというか、eed3si9nさんも色々と忙しく最低限自分が使う分だけやったあとそこまでしっかりとはメンテしてない？かつ、sbtもparadoxに移行する可能性があるとか？ https://github.com/sbt/website/issues/281 色々と微妙な状況でした。

あと他に選択肢ないわけでもなかったが、とくに反対意見なさそうだし、すごく悩むよりもやる気があるうちにさっさとやってしまったほうがいいか、という気持ちにより、わりと独断で勝手にparadox使ってみることにしました。



そもそもparadoxの説明してませんでしたが、簡単に知ってることを書いておくと

  • markdownからhtml生成する系のツール
  • playframeworkやakkaでやっていたのをsbt pluginにしたやつ(たぶん細かい機能は色々違うが)
  • akka-httpのドキュメントで使われてる
  • lightbendの他のなにかも、そのうちコレに移行するのだろうか？
  • 個人的に最大の特徴としては、コンパイル済みの任意の言語のコードがmarkdownの一部で参照することにより、typesafeなドキュメントが書けたり、その他リンクなどもチェックが働く点
  • sbt-site pluginとの連携がある https://github.com/sbt/sbt-site
  • その他色々あるが、公式ドキュメントみてくれ http://developer.lightbend.com/docs/paradox/latest/


というわけで、ここから先まずやったこと

  • 本体のソースコードと同じリポジトリでもすごく不都合あるわけでもなかったが、なんとなく一緒になってる必要もないな、と思ってリポジトリ分けた https://github.com/unfiltered/website/
    • メリットもデメリットもあるかもしれないが？　
    • リリース版のjarを使うようにしたので、たとえばSNAPSHOTの最新のclassやmethodを参照したコードをドキュメントから参照する形式が不可能になる？が、自動ビルドをやる予定だし、SNAPSHOT版の記述があるとかえってユーザーが混乱することがあり得るので、あえてそれはいいか、みたいな割り切り。それはそもそもversion毎にページ分ければいいのだが、今回はひとまずやってない
  • 出来る限り @@snip という、コンパイル済みのコード参照機能を使うように修正(超地味な作業で時間かかった)
  • その他、pamfletとparadoxで変数参照の方法などが違った部分を修正
  • リンクもtypesafe ?な方式に変更
  • 移行の過程で判明した古い記述削除、修正
  • 一応履歴残した方がいいか？でも全部残すのもアレだな、と思ったのでgit filter-branchした https://github.com/unfiltered/website/commit/953f3439a04

その後デプロイ関連


その他今回paradox使った感想

  • コンパイルだけなら、gitbook + tutよりとてもはやい
    • もちろんREPL形式で実行結果まで表示できるのはtutにしか出来ないことだが、実際の実行必要ないケースも結構あるし、これで十分な場合もわりとありそう
  • pamfletはファイル名の命名規約で勝手にページ順決まるの便利
    • 逆に柔軟性ないともいえるが、別にファイル名とページ名の関係とかあまりこだわらないなら、pamfletのほうが断然楽だと思った。
    • いや、pamfletは指定しようと思えば指定可能(？)
  • インラインで埋め込めないことによるメリット、デメリット
    • インラインで書けず、importするためにコメントで印つけるのは、地味に面倒。だがまだこの程度なら許容範囲かなぁとも思う
    • 複数言語(例: 日本語と英語)対応する場合は、インラインで埋め込む形式だとコード丸ごとコピペしないといけないが、この方式のほうがコード部分は共有できてよさそう。Scala公式のドキュメントも、paradoxつかってコードコンパイルしてほしい
  • そもそもJavaやそれ以外の任意の言語importできる。まぁparadoxがある程度Scala用に作られてる感はあるので、不可能でもないが、他の言語界隈の人が使うことはないだろうが
  • sbt-pamfletやtutみたいにコンパイラに依存しないことによるメリット
    • コンパイラに依存すると色々面倒なわけですが、paradoxはシンプルにコメントで印付けた部分をimportしてくるだけなので、そのあたりはよさそう


だいたいこんな感じかなぁ。unfilteredそのものや、こういう古いOSSメンテして引き取ったりしてることや、いかにしてコストを減らしつつメンテし続けるか？みたいなあたりを本当は色々書きたいが、長くなったし、なによりblog書いてる暇があったらまだまだやること残ってるので、そっちをやりたいので今日はこのあたりで。

しばらく放置されてた分、貢献出来る部分まだ色々残ってるので、貢献してくれる人募集中ですよ