Common Lisp ドキュメンテーション生成ライブラリ あれこれ

こんにちは。

みなさん、自分で作ったCommon Lispライブラリで、きちんとdocstringを書いて、API文書を生成したいと思っても、APIドキュメントのジェネレータがたくさんありすぎてどれを使えばいいのかわからない、という事はありませんか？そういうわけで、Clikiに載ってるライブラリをチェックして、おすすめと向き不向きを紹介してみることにしました。

Documentation Tools

しかしほんとにたくさんあります。CLのライブラリってみんながみんな自分勝手にオリジナルを一人で書いてしまうので、たいてい乱立していますよね。どうにかならないかな・・・。

ここのリストの上から順に、感想を書いていきます。

Albert

ASDF defsystemの拡張ですね。2009-07-16で更新停止。文字列はJavadoc,Doxigen互換だと言っているのですが、Exampleがありませんので、使い方がよくわかりません。

(asdf:defsystem :langband-engine
    :name "Langband Engine"
    :author "Stig E Sandoe"
    :version "0.1.7"
    :licence "GPL"
    :properties ((#:author-email . "[e-mail]")
         (#:date . "Summer 2003")
         ((#:albert #:output-dir) . "albert-docs/")
         ((#:albert #:formats) . ("docbook")) ...

(require :albert)
(load "langband-engine.asd")
(albert:document-systems :langband-engine) ;; changed from v0.2

Atdoc

出力形式: html,latex,info
生成サンプル

(atdoc:generate-html-documentation
   '(:blocks-world :blocks-world-goals) ; package名
   output-directory                     ; pathname
   :index-title "Blocks World API reference"
   :heading "The Blocks World"
   :single-page-p t      ;optional
   :include-internal-symbols-p nil)

CL-API

スタイルやjsも込み込みのドキュメンテーションが生成されます。
自分が生成して欲しいのはhtmlだけですので、
シンプルさという意味ではよくありません。
自分は使わないと思います。

出力形式: html
生成サンプル

(api-gen :clonsigna #P "/tmp/"
         :exclude-func (lambda (s) (or (starts-with "imap" 
                                                     (format nil "~a" s))
                                        (starts-with "bodystructure" 
                                                     (format nil "~a" s))
                                        (starts-with "structure"
                                                     (format nil "~a" s)))))

CLOD

Org-modeを出力します！
Orgはmarkdownと同じような軽量マークアップ言語。
emacsユーザでorgをメインに使っている人にはお勧め。
orgからTeXやhtml,(tex経由で)pdfも作れます。
orgはinfojsに対応しているので、簡単なスライドを作成するのもできますね。
詳細はorg-modeのHPへ。

追記：　つかってみたんですが、うーん、いまいち。

Declt

作者のHP 切り替えないとフランス語になります
出力ファイルが階層化されすぎていて、読むのが辛いかも。
また、docstringのかかれていない関数も全部出力し、
しかもおせっかいなことにpackage名やファイルの場所を全部にくっつけてくれます。
まあ、設定で減らせるのかもしれませんが・・・

その他にコメントすべき点としては、見た目がhyperspecに似せてあります。

出力形式: texinfo
生成サンプル

(declt SYSTEM-NAME &key LIBRARY-NAME TEXI-FILE ... )

DOCUMENTATION-TEMPLATE

CL-PPCRE,VECTOなどの作者と同一人物、Edi Weitz氏によるツールです。
必要最小限、コンパクトで読みやすいAPI DOCを作る人だなあと思っていたら、やはりそうでした。
テンプレートを作るだけで、詳細は後からhtmlで書けという方針のようです。

出力形式: html
DOCUMENTATION-TEMPLATE

ほか

http://weitz.de/cl-ppcre/
http://weitz.de/cl-interpol/
http://weitz.de/cl-fad/
http://weitz.de/hunchentoot/

syntax:

(create-template package &key target maybe-skip-methods-p subtitle if-exists if-does-not-exist)
 ;; => result

TINAA

metabangの人です。例は以下。どこに何があるのかわかりにくいです。
私は使いません。パッと見てわからないのならDOC文書としては適してないかも・・・。

TINAA
cl-containers

SB-TEXINFO

もともとSBCLに付属していたツールで、ほかでもつかえるようにと分離されたもの。
これが吐くTeXinfoはごちゃごちゃとしていないので分かりやすそうです。

SB-TEXINFO

このサイト自体もおそらく sb-texinfo で生成されています。
サイトのソースを見ると、出力されたファイルを makeinfo --html で変換すれば html になるようです。

ライブラリとしては、２つの使い方があります。

1. 適当にぱっと文書を作りたいときには、 document-package でワンコマンドで生成できます。
2. 一方、docstringとは別にちゃんと説明も追加してきちんとしたマニュアルを作りたい時は、 generate-includes を用いることで、別のTeXinfoドキュメントからインクルードするためのフォーマットで書きだしてくれます。

きっと自分はもっぱら1のやりかたばっかりになりそうですね。

quickdocs

更新内容としてはこれ。 http://quickdocs.org/ メンテナンス中のようです?(6/7)
quicklispに登録されていれば自動である程度見やすく表示してくれます。
玉に瑕としては

• 時々重複したシンボルが表示されている。
• docstring の無い要素は、他と同じ節としてではなく、重要度を低く、小さく見せたらいいと思います。
• readme を検索して自動でリンクを貼ってくれたりすると素晴らしいかも。
• コメントやstring で `symbol' のように囲むとハイライトされますよね? あれがリンクになっていればいいなあとか。

いや案があるならオープンなんだからコミットしろよという感じですが(笑)

結論

CLODかsb-texinfo,あるいはquickdocsに丸投げ。

ところで: hyperdoc関連

SLIMEの C-c C-d C-h ってみなさんつかってますか？今いるカーソルの直前の
シンボルをHyperspecから検索して、該当ページこれをブラウザで自動で開いて
くれる機能です。私は、関数の仕様を忘れた時とかに重宝しています。これが
他のライブラリでも使えたらいいですよね、という話題がhyperdocプロトコル
だそうです。

HYPERDOC

使うには、上のアドレスからダウンロードした後、中にあるslime用のパッチ
を当てればよいのだそうです。じぶんもこれからやってみようと思います。

ライブラリの作成者側は、defsystemで :WEAKLY-DEPENDS-ON に :hyperdoc と
指定して、その後ライブラリの中で以下のように、自分で生成して公開してい
るドキュメンテーションのアドレスを登録すればよいそうです。

(register-documentation package
       :base-uri (format nil "http://weitz.de/~(~A~)/" package)
       :relative-uri-function (formatter "#~(~A~)"))

Usage (Library Hacker)

hyperspec-lookup

似たことを考える人はほかにもいるようで。

ただ、こちらはhyperspecとMOPだけにしか対応していません。

(require :hyperspec-lookup)
(hs:lookup "defun")
;; -->  "http://www.lispworks.com/reference/HyperSpec/Body/m_defun.htm"

;; Note how sometimes symbols in the Hyperspec and MOP overlap (in
;; those cases the library will always return the Hyperspec URL):

(hs:hyperspec-lookup "add-method")
;;  "http://www.lispworks.com/reference/HyperSpec/Body/f_add_me.htm"
(hs:mop-lookup "add-method")
;;  "http://www.alu.org/mop/dictionary.html#add-method"

とりとめのないことを書き連ねた記事ですが、こんなところでしょう。