NGUI のプログラムを元にオフラインでも使えるAPIリファレンスを作る方法

Unity Advent Calendar 2012、8日目のMikamiさんに続いて9日目を担当させて頂く @nakamura001 です。よろしくお願いします。

折角のイベント事ですからちょっと毛色の違うUnityネタを書こうかと思います。内容は「オフラインでもガリガリUnityプログラムが出来る様にリファレンスを整備しよう」というものです。これでネット環境が無い場所でのプログラムも怖くない!!

作成するリファレンスのフォーマット解説

NGUI のプログラム書き込まれているドキュメンテーションコメントを元にリファレンス(chmファイルやdocsetファイル)を作成する方法を解説します。

ちなみにchmファイルはこんなアイコンのファイルで、Windowsでよく使われる一般的なヘルプファイルです。

docset とは Mac で使われるAPIのリファレンスなどヘルプファイル的な用途に使われるファイル(実体はフォルダ)です。 Xcode に付属している API リファレンスなどはこの形式のファイルが使われています。

こんな本が並んだアイコンがdocsetファイルのアイコンです。

余談ですがdocsetファイルは以下のフォルダなどに保存されています。

~/Library/Developer/Shared/Documentation/DocSets/
/Applications/Xcode.app/Contents/Developer/Documentation/DocSets/
/Library/Developer/Documentation/DocSets

今回は docset を Dash で使用する事を前提とした作業手順を解説します。 Dash についてご存知で無い方はこちらの記事を参照下さい。

高速にドキュメントの検索が可能なアプリ「Dash」(Unityのドキュメントも検索可能) - 強火で進め
http://d.hatena.ne.jp/nakamura001/20120702/1341233553

ツールを準備

まず、プログラムのクラスやメソッドの情報をHTMLファイルやchmファイルにする為に Doxygen を導入します。

こちらのページの

Doxygen
http://www.stack.nl/~dimitri/doxygen/

このリンクをクリックするとダウンロードページが表示されます。

Windows向けにchmファイルを作成

まずはWindows向けのchmファイル方法を解説します。

chmファイルを作成する為に「HTML Help Workshop」をダウンロードしておきます。

Download HTML Help Workshop and Documentation from Official Microsoft Download Center
http://www.microsoft.com/en-us/download/details.aspx?id=21138

htmlhelp.exe が今回使用するアプリのリンクです。

chmファイルを作成する為に必要なHTMLファイルや関連ファイルを Doxygen で作成します。

今回は簡単に説明できる様にCドライブに NGUI_work というフォルダを作成し、そこで作業をする事にします。
1. Cドライブの直下に NGUI_work というフォルダを作成。
2. NGUI_work フォルダに NGUI のフォルダをコピー。
3. NGUI_work フォルダに Output という名前でフォルダを新規作成。

4. Doxygen を開いてデフォルトで選択されているWizardタブの Topics の Project から順番にキャプチャ画像の通りに設定。

項目	設定値
作業フォルダ	c:\NGUI_work
プロジェクト名	NGUI
生成元ファイル	C:\NGUI_work\NGUI\Scripts
出力先ディレクトリ	C:\NGUI_work\NGUI\Scripts

ここからは Export タブでの設定になります。タブを切り替えて下さい。

項目	設定値
CHM_FILE	NGUI.chm

5. 「Run doxygen」ボタンを押してHTMLファイルや関連ファイルの生成を開始します。処理が完了すると Output フォルダにファイルが生成されます。

6. HTML Help Workshop を起動し、ファイルを開くアイコンをクリック。表示されたダイアログで 2. で生成された html フォルダの中に有る index.hhp ファイルを選択。

7. コンパイルアイコンをクリックし、chmファイルを生成。

これで html フォルダの中に NGUI.chm という名前のchmファイルが生成されます。

例えば UISprite と検索するとこの様に表示されます。

Mac向けにdocsetファイルを作成

Doxygen を使ってHTMLファイルを作成します。HTMLファイルはdocset(Documentation Set)を作成する時に使います。

作成手順はこの様になります。
1. 作業用フォルダとして、新規にフォルダを作成。
2. そこに NGUI のプログラムをフォルダごとコピー。
3. 出力先のフォルダとして 1. の作業用フォルダに Output というフォルダを作成。
4. Doxygen の設定ファイルとして doxygen.config というファイルを同じフォルダに作成。
ファイルの内容は以下の様に記述します。

GENERATE_DOCSET        = YES
SEARCHENGINE           = NO
DISABLE_INDEX          = YES
GENERATE_TREEVIEW      = NO
GENERATE_LATEX         = NO
GENERATE_HTMLHELP      = YES
RECURSIVE              = YES

PROJECT_NAME           = NGUI
OUTPUT_DIRECTORY       = Output
INPUT                  = NGUI/Scripts
DOCSET_BUNDLE_ID       = com.example.NGUI

【パラメータの説明】

パラメータ	説明
GENERATE_DOCSET	docset作成のための関連ファイルを作成するか
SEARCHENGINE	HTML 出力に検索機能を含めるかどうか
DISABLE_INDEX	各ページの上部にある簡約インデックスのオン/オフ
GENERATE_TREEVIEW	ツリー状のインデックス構造の生成の有無
GENERATE_LATEX	LaTeXの出力を行うか
RECURSIVE	INPUTに指定ファイルのサブディレクトリのファイルも対象にするか
PROJECT_NAME	生成されるドキュメントのプロジェクト
OUTPUT_DIRECTORY	生成されたドキュメントが置かれるパス。相対パスか絶対パスで指定
INPUT	生成元のファイル
DOCSET_BUNDLE_ID	docset向けのバンドル文字列

Doxygen
http://www.doxygen.jp/config.html

ここまでの作業が終わるとこの様なフォルダ構成になります。

5. ターミナルを開き、作業フォルダ( doxygen.config が有るフォルダ)に移動し、以下のコマンドを実行。

/Applications/Doxygen.app/Contents/Resources/doxygen doxygen.config

すると Output フォルダにファイルが生成されます。

6. Ouput/html に有る Info.plist をエディタで開き、 dict タグの中に以下のタグを追加します。

     <key>DocSetPlatformFamily</key>
     <string>unity3d</string>

7. ターミナルで Ouput/html に移動し、 make コマンドを実行します。

これで Ouput/html フォルダの中に docsetファイル( com.example.NGUI.docset ) が生成されます。

Dash がインストールされている環境でこのファイルをダブルクリックするとこの様に Dash にリファレンスが追加されます。

ちなみに 6. で行った作業はここの一覧に影響が有る作業となります。 6. で unity3d を指定したためアイコンが自動的に Unity のものになっています。

以上の作業でオフラインでも NGUI のAPIについて検索する事が出来る様になります。

他のインストール方法

他のインストール方法としては make を実行したフォルダで以下のコマンドを実行すると

make install

以下のフォルダにコピーされるので

~/Library/Developer/Shared/Documentation/DocSets/

このフォルダで一括管理するというのも良いでしょう。

Unity Advent Calendar 10日目は id:shinriyo さんによる「GoKit実践　シーン3. Tween Flow」です。

強火で進め

このブログではプログラム関連の記事を中心に書いてます。