2012/06/18

appledocのドキュメント作成を自動で行うようにする

前回の記事「appledocを使ってObjective-CソースをXcode Organizerで表示できるようにする」によって、Organizerでドキュメントを表示できるようになりました。

今回はこれを自動化して、コンパイル時やコミット時にドキュメント作成できるようにしてみます。紹介するのは次のような3つの方法です。

  • コンパイル時に作成
  • コミット時に作成
  • Jenkinsの利用

準備: plistの利用

前準備として、appledocを簡単に利用できるように設定します。

appledocはコマンドラインで指定した場所にAppledocSettings.plistがあれば、その設定を読み込みます。このファイルはkeyの部分にはコマンドラインオプションを指定するような形式になっています。

例えば、次のようなAppledocSettings.plistを用意しておくと、~/appledoc .のみでドキュメントを作成できるようになります。

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
            "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>--project-name</key> <string>MySampleApp</string>
      <key>--project-company</key> <string>Safx</string>
      <key>--company-id</key> <string>com.blogspot.safx-dev</string>
      <key>--keep-undocumented-objects</key> <true/>
      <key>--keep-undocumented-members</key> <true/>
       <key>--repeat-first-par</key> <false/>
       <key>--input</key>
          <array>
            <string>MySampleApp</string>
          </array>
    </dict>
    </plist>

なお、グローバル設定は~/.appledoc/GlobalSettings.plistに置くこともできます。このとき、appledocはGlobalSettings.plistの設定を読んでからAppledocSettings.plistの設定を読み込みます。

コンパイル時に作成

Xcodeのビルド後の自動アクションでドキュメントを作成しようという方法です。次のような手順で設定します。

  1. [Product]→[Edit Scheme…]で[Build]タブ内の[Post-actions]を選択します
  2. 左下の + ボタンをクリック
  3. [provide build settings from]にターゲットを指定。これによってPROJECT_DIRの値が決定します。
  4. エディット部に~/appledoc ${PROJECT_DIR}と入力して[OK]

なお、リリース時のみドキュメント作成したいときは次のようにすればよいです。

    if [ ${CONFIGURATION} != "Release" ]
    then
        ~/appledoc
    fi

この方法はコンパイルごとに実行されるので、更新されないで無駄に実行することが多くなります。 しかし、Xcodeを利用するだけで常に最新のドキュメントが得られるようになるため、小規模なプロジェクトならこれで十分かもしれません。

コミット時に作成

Mercurialのフックを用いて、コミット時にそのリポジトリにAppledocSettings.plistがあればappledocを実行させる方法です。

まず、スクリプトappledoc.shを作成します (chmod +x ~/src/appledoc.shを忘れずに)。

    #!/bin/sh
    [ -f AppledocSettings.plist ] && ~/appledoc .

そして、.hgrcに次の2行を追加します。

    [hooks]
    commit.appledoc = ~/src/appledoc.sh

これで、リポジトリを作成してAppledocSettings.plistを設定すれば、後はコミット時にドキュメントが更新されるようになります。

Jenkinsを利用して自動テスト実行後に作成

ここでは、自動テストに成功したときに、続けてドキュメント作成を行うような方法を説明します。自動テスト用プロジェクトを作成する方法については以前の記事「Jenkinsでテストとカバレッジの結果をグラフ表示できるようにする」を参照してください。

次のような手順で新規プロジェクトを作成・設定します。 なお、既にテスト自動実行用のジョブMySampleTestがあり、そのワークスペースが/Users/safx/.jenkins/jobs/MySampleTest/workspaceであるとします。

  1. [新規ジョブ作成]で[MySampleDoc]を[フリースタイルプロジェクト]で作成
  2. MySampleDocの[設定]で[プロジェクトの高度なオプション]→[カスタムワークスペースを利用する]にチェックして、/Users/safx/.jenkins/jobs/MySampleTest/workspaceを指定
  3. [ビルド・トリガ]の[他のプロジェクトの後にビルド]をチェックして、MySampleTestを指定
  4. [ビルド手順の追加]→[シェルの実行]を追加
  5. ~/appledoc --exit-threshold 1 .を[シェルスクリプト]に追加
  6. 下の[Save]をクリック

これで、MySampleTest成功時にMySampleDocが実行されてドキュメントが更新されます。ちなみに、--exit-threshold 1はwarningのみなら終了コードを0とみなすオプションです。これを指定しないとJenkins側でエラー終了と判断されてしまいます。この設定はAppledocSettings.plistに書いてしまってもよいでしょう。

Jenkinsを利用すると、このようなリポジトリ更新トリガによる作成だけでなくcronのような指定時間による作成などにも対応できますし、エラー報告もわかりやすく参照できるため、Jenkinsを既に導入しているなら利用しない手はないでしょう。

また、Jenkinsを利用してappledocでHTMLを出力するようにしておけば、ブラウザから常に最新のドキュメントを見ることができるようになるため、複数人で開発している場合にはよいかもしれません。

まとめ

appledocのドキュメントを自動で作成されるようにする方法について説明しました。

関連リンク

ラベル: , , ,

0 件のコメント:

コメントを投稿

注: コメントを投稿できるのは、このブログのメンバーだけです。

登録: コメントの投稿 (Atom)