SenchaのAPIリファレンスサイトであるSencha DocsがExt JS 4を使って実装されているのは知っていて、Ext JS 4をガシガシ使っているところを見ると、Senchaの中で作られたクローズドなフレームワークなんだろうなと思い込んでいた。しかし、つい最近TitaniumのAPIリファレンスを見たら、まったく同じ構成をしていることに驚いて、オープンソースのフレームワークなのか!?と思い、Xenophyの@kotsutsumiさんに訊いたら「JSDuckのことですね。」と教えてくれた。
開発したのはやはりSenchaの中の人なんだが、GitHub上でソースが公開されていた。去年のSenchaCon 2011でもJSDuckのセッションがあって、そこではライブコーディングによるデモが行われている。
ムービーは1時間弱と長いのだが、時間のある人は是非ライブコーディングを見てほしい。
JSDuckはRubyのgemパッケージとして登録されているので、Rubyが使える環境であればすぐに使うことができる。
$ gem install jsduck
--help=fullオプションを指定すると、コマンドラインオプションの全リストが表示される。
$ jsduck --help=full
GitHub上のWikiのGuideとAdvanced Usageも参考にするといいだろう。
もともと、Ext JS 4やSencha TouchなどのAPIリファレンスを自動生成するために開発されたこともあり、JavaScriptのライブラリに特化した作りになっているが、例えば「ガイド」に関しては（Ext JS 4の例）、JavaScriptのライブラリでなくても利用することができる。
ここではトップページとガイドだけのオンラインヘルプを作ってみる。
まずは作業用のディレクトリを作成して、そこにwelcome.htmlというHTMLファイルを作る。
$ cd ~ $ mkdir help $ cd help $ vi welcome.html
welcome.htmlは完全なHTMLではなく、bodyタグの内側だけを記述する。
<h1>Inhale 'n Exhale Online Help</h1> Welcome to <a href="http://h2plus.biz/hiromitsu/">Inhale 'n Exhale</a>!
welcome.htmlを書いたら、jsduckコマンドを実行してビルドする。
$ jsduck -o public --welcome=welcome.html
-oオプションで指定しているのは、成果物の出力先となるディレクトリ名。実行前に存在していなくても構わない。そして、先ほど書いたwelcome.htmlを--welcomeオプションに指定する。すると、publicディレクトリ配下に、Ext JS 4を含む、HTML、CSS、JavaScriptがビルドされる。
public/index.htmlをブラウザで開けば、できあがったトップページをすぐに確認することができる。別にWebサーバーを立てる必要もない。ローカルアクセスでいい。
トップページのサンプル（別タブで開きます）
次にガイド。トップページほど単純ではないが難しくもない。まずはguidesという名前（固定）のディレクトリを作る。そして、guidesディレクトリの下にページ毎のサブディレクトリを作る。各サブディレクトリの中には、README.mdという名前（これも固定）のテキストファイルを置く。
$ mkdir guides $ cd guides $ mkdir programming $ vi programming/README.md
README.mdは拡張子からもわかるように書式はMarkdownで書くのがルール。
# プログラミング C/C++、JavaScript、PHPなど。
同じようにwordpressディレクトリも作っておく。
$ mkdir wordpress $ vi wordpress/README.md
# WordPress WordPressのカスタマイズ関連。
こういった感じで、guidesディレクトリ配下にコンテンツを作っていき、最後に「ガイド」のツリービューを構成するためのJSONファイルをトップディレクトリに置く。
$ cd ~/help $ vi guides.js
[
{
"title": "カテゴリの紹介",
"items": [
{
"name": "programming",
"title": "プログラミング",
"description": "プログラミングとは何か？"
},
{
"name": "wordpress",
"title": "WordPress",
"description": "WordPressとは何か？"
}
]
]
JSONは、トップがオブジェクトの配列。各オブジェクトはtitleとitemsを持っていて、これが章のような枠組みを作ってくれる。titleが章のタイトルとしてツリーに表示される。
itemsはオブジェクトの配列になっていて、各オブジェクトはname、title、descriptionを持っている。nameは先ほどREADME.mdを置いたサブディレクトリ名に対応する。titleはツリーのページ名として表示され、descriptionは右側のコンテンツで概説として表示される。JSONに書いた内容と表示内容との対応は、実際にできあがったものと見比べてもらうのが一番だろう。
jsduckでビルドして、先ほど開いたブラウザをリロードしてみよう。
$ jsduck -o public --welcome=welcome.html --guides=guides.json
ガイドのサンプル（別タブで開きます）
ここでは必要最低限のファイル、必要最低限のコマンドラインオプションしか使わなかったが、タイトルを書き換えたり、アイコンや画像を差し替えたり、独自のCSSを適用させたり、ある程度のカスタマイズはファイル構成とコマンドラインオプションだけで実現できるようだ。Titaniumのようにページ全体のテーマを変えるとなると、Ext JSやSASSの知識が必要になるんだろう。
JSDuckが生成するコンテンツはExt JS 4アプリケーションなので、Ext JS 4がサポートしているブラウザでは問題なく動作すると言える。つまり、ブラウザ依存の振る舞いの違いなどに余計な体力を奪われず、「ドキュメントを書く」という仕事に集中できるのが素晴らしいところだ。
新しいページを選べばタブとして開いてくれるし、既に開かれたページであれば既存のタブにフォーカスが移る。しかも、開いたタブはすべてブラウザのローカルストレージに保存されているので、ブラウザを閉じても以前開いていたタブが復元する。他にもJSDuckが提供してくれる機能がたくさんあるが、これをイチから作っていたら相当大変だ。JSDuckをオープンソースとして公開してくれたSenchaの開発者に感謝、感謝である（GitHubのコミットログを見ると、メインのコミッターはReneという女性っぽい）。