More Related Content
Similar to AsakusaのドキュメントをDashで見たい
Similar to AsakusaのドキュメントをDashで見たい (20)
AsakusaのドキュメントをDashで見たい
- 2. NAUTILUS
2
自己紹介
青江崇
(株)ノーチラス・テクノロジーズ所属
Twitter ID: aoetk/ HatenaID: aoe-tk
かつてはSI屋でオンライン系システムのアーキテクチャ 設計をやっていたりRIA開発をしていたりと、うちの会 社では異色のフロント寄りの人間です
GUI技術にも関心があって日本JavaFXユーザーグルー プでも時々発表とかしてます
- 3. NAUTILUS
3
今日のお話
Mac向けAPIドキュメントブラウザDashにAsakusaFrameworkのドキュメントを組み込む方法について解 説します
すいません、Mac限定の話になります…
(個人的には最近Appleに飽きてきましたが)
- 4. NAUTILUS
4
Dashって何?
http://kapeli.com/dash
APIドキュメントブラウザ+コードスニペット管理ツール
–様々なプログラミング言語、フレームワークのAPIリファレンス (150種類以上!)をまとめて閲覧、検索できる
–ドキュメントセットは第3者がコントリビュート可能
有償のツールだが無償でも利用可能
–無償の場合は時々ウェイト画面が表示される
様々なIDEやエディタと連携が可能
- 6. NAUTILUS
6
Asakusaで開発しているときに考えた…
ホスト言語はJavaなので、JavaのAPIリファレンスは やっぱり頻繁に見る
–それはDashで閲覧
加えてAsakusaFrameworkのドキュメントも常に側に 置いておきたい
–特に演算子リファレンス!
どっちもDashでまとめて閲覧したい!
というわけでAsakusaのドキュメントを Dashに取り込んでみました
- 7. NAUTILUS
7
Dashのドキュメントセットについて
Dashは以下の構造を持つドキュメントディレクトリ (Docsetと呼ぶ)を取り込むことが可能
DocumentName.docset
└── Contents
├── Info.plist
└── Resources
├── Documents
│ ├── HTMLなど
│ …
└── docSet.dsidx
SQLiteのテーブルとして 用意したインデックス
ドキュメントはHTML
各種メタ情報を記述
ルートディレクトリ
- 8. Copyright © 2011 Nautilus Technologies, Inc. All rights reserved.
NAUTILUS
8
Proprietary & Confidential
それでは取り込んでみましょう
- 9. NAUTILUS
9
ドキュメントの入手
AsakusaFrameworkのドキュメントはGitHubに公開 されているソースに含まれている
ビルドにはSphinxを利用
–予めSphinxをインストールしておく必要があります
Macには最初からPythonが入っているので、ターミナルから “easy_install-U Sphinx” と打てばOK
- 10. NAUTILUS
10
ドキュメントのビルド
まずはAsakusaFrameworkのcloneから
$ gitclone https://github.com/asakusafw/asakusafw.git
先にJavaDocの生成を
–<project_dir>/target/site/apidocsに出力されます
$ cd asakusafw
$ mvnjavadoc:aggregate
ドキュメントディレクトリに移動してビルド
–<project_dir>/docs/ja/build/html に出力されます
$ cd docs/ja
$ make html
- 11. NAUTILUS
11
JavaDocのインデックスを作成
Dash側でJavaDoc用のDocset生成ツールが用意されて いるので、それを利用する
–http://kapeli.com/javadocset.zip
適当なディレクトリ上で対象となるJavaDocのディレク トリを指定して実行するとDocsetが生成される
$ ./javadocsetAsakusaFw<project- dir>/target/site/apidocs
-> ディレクトリAsakusaFw.docsetが生成される
Docsetの名前を指定
- 12. NAUTILUS
12
Asakusaのドキュメントをマージ
DocsetにAsakusaのドキュメントを移してくる
AsakusaFw.docset
└── Contents
├── Info.plist
└── Resources
├── Documents
│├── allclasses-frame.html
│├── allclasses-noframe.html
│├── com
││└── asakusafw
…
docs/ja/build/html
├── _downloads
│└── user-guide.html
…
├── genindex.html
├── index.html
├── introduction
…
AsakusaFw.docset
└── Contents
├── Info.plist
└── Resources
├── Documents
│├── _downloads
...
│├── api
││├── allclasses-frame.html
││├── allclasses-noframe.html
││├── com
│││└── asakusafw
...
│├── genindex.html
│├── index.html
│├── introduction
Docset
Asakusaドキュメント
apiディレクトリを掘って、 JavaDocを移動
Documents 直下にコピー
- 13. NAUTILUS
13
インデックス修正
JavaDocの位置をずらしたので、インデックスを修正
$cd AsakusaFw.docset/Contents/Resources
$ sqlite3 docSet.dsidx
sqlite> update searchIndexset path=replace(path, 'com/asakusafw', 'api/com/asakusafw');
Macには最初からSQLiteが入っています
- 14. NAUTILUS
14
メタデータ修正
メタデータファイルInfo.plistを修正し、Asakusaのド キュメントページをトップページにする
–<Docset_dir>/Contents の直下にある
<?xml version="1.0" encoding="UTF-8"?>
<plistversion="1.0">
<dict>
…
<key>dashIndexFilePath</key>
<string>overview-summary.html</string>
<key>DashDocSetFamily</key>
…
</dict>
</plist>
<?xml version="1.0" encoding="UTF-8"?>
<plistversion="1.0">
<dict>
…
<key>dashIndexFilePath</key>
<string>index.html</string>
<key>DashDocSetFamily</key>
…
</dict>
</plist>
dashIndexFilePath の値を修正
- 15. NAUTILUS
15
もう一修正
Asakusaドキュメントのトップページにある、APIド キュメントのリンクをDocset内のAPIドキュメントに変 更しておく
–<Docset_dir>/Contents/Resources/Documents/index.html
<li><a class="reference external" href="http://asakusafw.s3.amazonaws.com/documents/0.6.2/release/api/index.html"> APIリファレンス</a></li>
<li><a class="reference external" href="api/overview-summary.html">APIリファレンス </a></li>
- 18. NAUTILUS
18
まとめ
Dash、いいツールなのでMacユーザーな方は是非使っ てみよう
–Windowsで似たようなツールないですかね|ω・`)チラ
Asakusaの公式ドキュメントはGitHubで公開している ソースの中に含まれており、ビルドが可能
–ドキュメントを手元に置きたい方、現場が閉鎖環境な方は是非
–ドキュメントに誤りを見つけた方はプルリク送ってもいいのよ