前の記事で Docsetドキュメントブラウザ: Zeal を紹介した。
クロスプラットフォームな Docsetドキュメントブラウザ: Zeal
既に無数の言語やスクリプトのドキュメントが公開されているが、
それでも対応する Docset が手に入らない、
クローズドやプライベートなソフトウェア群の
自前APIドキュメントの Docsetを作る方法を紹介。
Doxygen
ソースコード・ドキュメンテーション・ツールである Doxygen を用いる。
各OSのバイナリがコチラ からダウンロードできる。
macOSはGUIフロントエンドが付属しているが(Windowsは未確認）
Linuxだと上記のバイナリにはGUIフロントエンドが入っていないので、
パッケージ管理ソフトからダウンロードする方が良いかもしれない。
Ubuntu の場合、以下で本体とGUIフロントエンドがインストールできる。
|
1 2 |
$ sudo apt-get install doxygen doxygen-gui |
ソースコードの解析
インストールした doxygen でソースコードを解析し、
Docset の元となるHTMLを生成する。
操作・オプション
GUIフロントエンド: Doxywizard をを起動する。
- 上部に作業ディレクトリを指定する。
- Wizardタブ Project項目：
Project Name, Source code directoryを指定, Scan recursively にチェック - 同Wizardタブ Mode項目：
All Entries を選択, Include cross-referenced ... にチェック -
同Wizardタブ Output項目：
HTMLにチェック, with navigation panelを選択, LaTexは外す -
Expertタブ HTML項目：
GENERATE_DOCSET にチェック, すぐ下の DOCSET_BUNDLE_ID を指定 -
Runタブ:
Run doxygen を押して解析、HTML生成を行う
各種オプションについて
一応、Dash開発者の公式によると
GENERATE_DOCSET, DISABLE_INDEX にチェックを入れて、
SEARCHENGINE, GENERATE_TREEVIEW のチェックを外すことを推奨している模様。
- GENERATE_DOCSET:
Docset用の追加インデックスファイルが生成されます（必須） - DISABLE_INDEX:
↓公式ページの上部メニューのようなインデックスを生成/表示しない - SEARCHENGINE:
ページ内に検索窓を設置する。
Wizardタブ Output項目の "With search function" に対応 - GENERATE_TREEVIEW:
↓公式ページの左側のようなツリーメニューを生成
Wizardタブ Output項目の "with navigation panel" に対応
Doxygen 公式ページのスクリーンショット
上記の手順では公式推奨と異なり、DISABLE_INDEX にチェック無し、
GENERATE_TREEVIEW にチェックが入った状態になっていると思います。
ちょうど↑公式ページのようなレイアウトになります。
お好みに合わせて適宜変更してください。
あとは巨大なプロジェクトの Docset を作る際には、
Expertタブ Project項目の CREATE_SUBDIRS に
チェックを入れる方が良いかもしれません。
デフォルトでは一つのDocsetディレクトリ/フォルダに全ての関連ファイルが入るので、
システムによってはパフォーマンスに影響が出るかもしれないとのこと。
そういう場合はこのオプションにチェックを入れると
細かくフォルダ分けをして、性能の劣化を抑止できます。
Docset 生成
macOS
macOSの場合は、作業ディレクト内で make でDocsetが生成されます。
Docset生成には Xcode内の docsetutil を使っているので、
Xcodeのインストールが必要です。
Linux/Windows
Dash公式によると、macOS以外でもDocset化は一応可能で
生成したHTMLに適切な Info.plist と SQLite database: docSet.dsidx を追加すれば良い。
その辺を良い具合にやってくれる dashing というのを見つけて、
一応Zealから読める Docset化には成功したので名前だけ紹介するが、
class, methodやfunction名などを抽出する selectors の設定で、
matchpath が現状のバイナリ配布版では正しく動作していないようなので、
この変の挙動が改善して正しくインデックスがつけられた際に改めて紹介する予定。