Clojureのドキュメント生成にmarginaliaを使う


Doccoというツール

Doccoというツールがあります。

これは、CoffeeScriptで書かれたツールで、JavaScriptで書かれているソースコードとそのコメントを整形して非常に見やすいHTMLとしてドキュメント化してくれるものです。

Clojureにはmarginaliaがある

Doccoはいろいろな言語用に移植されたりしていますが、Clojure用のものもmarginaliaという名前で存在します。

こんな感じでdescjopのコードもHTMLになりました。

marginaliaのコード自体、このツールでHTML化しているので見てみると面白いです。

ポイントは、ソースコードにシンタックスハイライトがされ、コードとコメントが1対1で左右に並ぶところでしょうか。一枚のHTMLとして生成されるので、扱いも楽です。

marginaliaの利用方法

利用方法はいたって単純で、ホームディレクトリにある.leinディレクトリ(このディレクトリにprofiles.cljなどとプロジェクトファイルに書くようにプラグインとして指定すると、全プロジェクト共通で使えるようになる)にて設定したら、あとは

[lein-marginalia "0.8.0"]

などと設定します。

ちなみに僕のprofiles.cljは今のところこんな感じです。

{:user {:plugins [[lein-idea "1.0.1"]
                  [lein-typed "0.3.5"]
          [lein-marginalia "0.8.0"]
                  [lein-kibit "RELEASE"]
                  [cider/cider-nrepl "0.8.2"]
                  ]
        :aliases {"slamhound" ["run" "-m" "slam.hound"]}
        :dependencies [[slamhound "RELEASE"]
                       [org.clojure/tools.trace "RELEASE"]]}}

設定を終えたら、ドキュメントを生成したいプロジェクトのディレクトリに移動し、下記コマンドを実行します。

$ lein marg

すると、プロジェクト内の直下に、docsディレクトリというものが出来、その中にuberdoc.html というHTMLファイルが生成されるので、これをブラウザで開きます。

という感じで設定とかもほぼいらず、ワンコマンドのみでドキュメントを生成できるので、おすすめです!

Comments are closed.