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

こんにちは。

みなさん、自分で作ったCommon Lispライブラリで、きちんとdocstringを書い
て、API文書を生成したいと思っても、APIドキュメントのジェネレータがたく
さんありすぎてどれを使えばいいのかわからない、という事はありませんか？

・・・ないですかね。まあ僕はあったんです。

そういうわけで、Clikiに載ってるライブラリをチェックして、おすすめと向
き不向きを紹介して見ることにしました。

まああるわあるわ

Documentation Tools

ほんとにたくさんあります。CLのライブラリってみんながみんな自分勝手にオ
リジナルを一人で書いてしまうので、たいてい乱立していますよね。どうにか
ならないかな・・・。話を戻して、注意点がひとつ。「僕はまだこれらのライ
ブラリをテストしていません」。そういうわけで、ここで書く内容はClikiの内
容プラス、それぞれのライブラリのチュートリアルの抜粋という程度の内容で
す。あくまで、ライブラリのセンスというか、筋というか、そういうものを手っ
取り早く感じていただいて、結果として皆さんがどれを使うか選ぶのに時間を
書けなくて済むようになればいいなあと思っています。

では、Clikiのものを上から順に。

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 . "stig@langband.org")
         (#: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などの作者と同一人物によるツールです。必要最小限、コンパ
クトで読みやすいAPI DOCを作る人だなあと思っていたら、やはりそうでした。
テンプレートを作るだけのようですが・・・？

出力形式: 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

２つの使い方があります。

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

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

結論

結論として、おすすめはCLODですね。
ごちゃごちゃしてないし、生成したものに加筆するのも、HTMLより容易ですから。

追記: 上でも書きましたが、超嘘です。CLODはそんなによくありませんでした。別のも使ってみます。

追記2: sb-texinfoが筋が良さそうです。

ところで: hyperdoc関連

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

HYPERDOC

http://common-lisp.net/project/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

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

http://common-lisp.net/project/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"

とりとめのないことを書き連ねた記事ですが、こんなところでしょう。
こんなの書いてないでレポート出して卒論かかないと;;