Grid Table 記法の紹介
Grid Table 記法の紹介

はじめに

みなさん haddock を使ってますか?

コメントを残す時に |^ を追加するだけで haddock 形式のコメントを残すことができます。

具体的にはこんな感じです。

コメントを haddock 形式にしてあげることで HTML のドキュメントがより充実するので、少ない労力で凄く楽しい気持ちになります。

stack を使っている場合はこのようにしてビルドするだけです。

$ stack haddock --open

今回、この haddockGrid Table 記法が追加されたそうなので、その機能についてご紹介したいと思います。

Grid Table 記法

以下の内容を参考としています。

haddock の更新

Grid Table を使うためには haddock-2.18.2 以上である必要があります。

現状 Hackage の最新版が 2.18.1 なので github の最新版を利用する必要があります。

$ haddock --version
Haddock version 2.18.1, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008

ここでは stack を使って最新版をインストールします。(その他の各種ビルド方法については Readme に詳しく載っているので、そちらをご参照ください)

$ git clone https://github.com/haskell/haddock.git
$ cd haddock
$ stack init
$ stack install

$ haddock --version
Haddock version 2.18.2, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008

$ cd ../

これで準備は整いました!

使ってみる

まずは新規プロジェクトを作って、初期状態で haddock を生成します。

$ stack new test-haddock-grid-table
$ cd test-haddock-grid-table
$ stack haddock --open

ブラウザが自動的に立ち上がるので Lib モジュールを見てみましょう。

初期状態で生成されるHTML
初期状態で生成されるHTML

someFunc だけの味気ない HTML ですね。haddock コメントを追加して、もう一度確認してみます。

$ stack haddock --open
haddock コメントを少し追加
haddock コメントを少し追加

ちょっと変わりましたね。

では、本題の Grid Table 記法で書いてみます。

ドキュメントを生成してみましょう。

$ stack haddock --open
Grid Table の生成に失敗
Grid Table の生成に失敗

失敗しました・・・。

これはどうやら stack が利用している haddock~/.local/bin にインストールした最新版の haddock を参照していないためです。

以下のコマンドで確認することができます。

$ stack exec -- which haddock
/home/bm12/.stack/programs/x86_64-linux/ghc-nopie-8.2.2/bin/haddock

$ stack exec -- haddock --version
Haddock version 2.18.1, (c) Simon Marlow 2006
Ported to use the GHC API by David Waern 2006-2008

ここで、stack が参照する haddock プログラムはシンボリックリンクとなっているため、一時的に上書きすることにしました。

$ stack path --compiler-bin
/home/bm12/.stack/programs/x86_64-linux/ghc-nopie-8.2.2/bin

$ ln -snf ~/.local/bin/haddock $(stack path --compiler-bin)/

これでやっと Grid Table が使えます!

$ stack clean
$ stack haddock --open
Grid Table のレンダリング結果
Grid Table のレンダリング結果

なかなかオシャレな感じです。

後片付け

シンボリックリンクを元に戻しておきましょう。

$ ls -l $(stack path --compiler-bin)
合計 32
lrwxrwxrwx 1 bm12 bm12    9 11月 27 00:39 ghc -> ghc-8.2.2*
-rwxr-xr-x 1 bm12 bm12  444 11月 27 00:39 ghc-8.2.2*
lrwxrwxrwx 1 bm12 bm12   10 11月 27 00:39 ghci -> ghci-8.2.2*
-rwxr-xr-x 1 bm12 bm12  108 11月 27 00:39 ghci-8.2.2*
lrwxrwxrwx 1 bm12 bm12   13 11月 27 00:39 ghc-pkg -> ghc-pkg-8.2.2*
-rwxr-xr-x 1 bm12 bm12  476 11月 27 00:39 ghc-pkg-8.2.2*
lrwxrwxrwx 1 bm12 bm12   29 12月 27 14:24 haddock -> /home/bm12/.local/bin/haddock*
-rwxr-xr-x 1 bm12 bm12  435 11月 27 00:39 haddock-ghc-8.2.2*
-rwxr-xr-x 1 bm12 bm12  408 11月 27 00:39 hp2ps*
-rwxr-xr-x 1 bm12 bm12  406 11月 27 00:39 hpc*
-rwxr-xr-x 1 bm12 bm12 1206 11月 27 00:39 hsc2hs*
lrwxrwxrwx 1 bm12 bm12   12 11月 27 00:39 runghc -> runghc-8.2.2*
-rwxr-xr-x 1 bm12 bm12  452 11月 27 00:39 runghc-8.2.2*
lrwxrwxrwx 1 bm12 bm12    6 11月 27 00:39 runhaskell -> runghc*

$ ln -snf $(stack path --compiler-bin)/haddock-ghc-8.2.2 $(stack path --compiler-bin)/haddock
$ cd ../
$ rm -rf test-haddock-grid-table
$ rm -rf haddock
$ rm ~/.local/bin/haddock

終わりに

stack の謎の挙動によって若干苦戦しながらも、無事に試してみることができました。

--with-haddock のようなオプションが欲しいなぁと感じました・・・。

Grid Table についてはデータベース系の操作結果などを例示する際に使えそうです!

以上です。