Jenkins+Doxygen+Dashで

詳細設計書配布を自動化する方法

Toru Hosokawa
twitter:@anton0825
facebook:toru.hosokawa1
github:hosokawa0825
blog:http://d.hatena.ne.jp/anton0825/

2014.2.15

詳細設計書(APIドキュメント)の問題点

  • メンテされない
  • 知りたい情報がどこにあるかわからない
  • ドキュメント書くのめんどくさい

解決策

  • メンテされない
    • ヘッダファイルにコメントを書き、Doxygenでドキュメントを生成することでメンテコストを下げる
    • さらに、Jenkinsを使って常に最新のドキュメントを生成・配布する
  • 知りたい情報がどこにあるかわからない
    • Dashで素早く検索出来るようにする
  • ドキュメント書くのめんどくさい
    • VVDocumenterを使って楽に書けるようにする

VVDocumenter

メソッドの手前で///を打つとAPIドキュメント用コメントが生成されるXCodeプラグイン

Doxygen

APIドキュメントを生成するツール

様々な形式に対応しています。

カスタマイズも結構できる

注意点

柔軟なだけあって、

設定項目がめちゃくちゃ多い！

おすすめ設定

# 解析したいプロジェクトの名前
PROJECT_NAME = "Your Project Name"
# 再帰的にソースコードのファイルを探索する
RECURSIVE = YES
# LaTeX で出力しない
GENERATE_LATEX = NO
# Graphviz で出力するための DOT ファイルを作る
HAVE_DOT = YES
# DOT ファイルの生成をマルチスレッドで行う
DOT_NUM_THREADS = 4
# コールグラフ (呼び出す側) を作る
CALL_GRAPH = YES
# コールグラフ (呼び出される側) を作る
CALLER_GRAPH = YES
# Dash用Docsetを生成する
GENERATE_DOCSET = YES
# 画面上部のタブをつけない
DISABLE_INDEX = YES
# 検索用テキストボックスをつけない
SEARCHENGINE = NO
# 画面左側のTreeViewをつけない
GENERATE_TREEVIEW = NO
# 出力先ディレクトリ
OUTPUT_DIRECTORY = "your output directory"
# 解析するソースコードがあるディレクトリ
INPUT = "project directory"

Dash

様々なAPIドキュメントを素早く検索出来るアプリ

Dashのいいところ

  • Apple公式APIドキュメントを検索するだけでなく、Doxygenで生成したAPIドキュメントを検索することも可能
  • doset feed(ドキュメントのバージョンとダウンロード先URLを書いたXMLファイル)を用意することで、ドキュメントの自動アップデートが可能

Jenkins+Doxygen+Dashで
APIドキュメントを配布する構成

JenkinsでDocset Feedとドキュメントを生成するスクリプト

# docset Feed用xmlを作成
sed "s/{BUILD_NUMBER}/${BUILD_NUMBER}/" menuFxDocsetFeedTemplate.xml > build/menuFxDocsetFeed.xml

# docsetを作成
doxygen
cd build/html
make
mv org.doxygen.Project.docset menuFx.docset
tar zcvf menuFx.docset.tgz menuFx.docset
mv menuFx.docset.tgz ${WORKSPACE}/build/menuFx.docset.tgz

DocsetFeedの例

Docset FeedとDocsetを開発用Macからダウンロード可能にする

Jenkinsの「成果物を保存」でDocset FeedとDocsetを保存するだけ

最後にビルドした際にできたDocset FeedとDocsetが
下記のようなURLからダウンロード可能 http://localhost:8080/job/pjname/lastCompletedBuild/artifact/docsetFeed.xml http://localhost:8080/job/pjname/lastCompletedBuild/artifact/docset.tgz

DashにDocset Feedを登録する

URLスキーマを使うとリンクをクリックするだけで
Docset Feedを登録できる。
dash-feed://の後にDocset FeedのURLを
URLエンコードしたものを繋げる。

dash-feed://http%3A%2F%2Flocalhost%3A8080%2Fjob%2Fpjname%2FlastCompletedBuild%2Fartifact%2FdocsetFeed.xml

最後に宣伝・・・

menuFxというMacアプリを最近リリースしました。
為替レートをメニューバーでチェックできるアプリです。

技術的なハイライト

  • ReactiveCocoaを使ってMVVMパターンでアプリを構成
  • クライアント・サーバ間の通信はSocket.io
  • サーバはNode.js