自動生成ドキュメントを無料で Web 上で最新に保つ（Wercker + Doxygen + Heroku）

はじめに

Doxygen を使うと，C/C++ をはじめとする様々な言語のコードから自動でドキュメントが生成できます．

ただ，Doxygen のドキュメント生成は，依存関係の画像なんかを生成するということもあり，結構遅いです．ビルドの度にやろうとは思えません．しかし，そこそこ新しいものがすぐ見れたら便利です．

そこで，push したら勝手にドキュメントを生成してどこかに置いておいてくれたら便利だなと思いませんか？これを，Wercker と Heroku を使って無料で実現します．

やり方

自分のコード (GitHub / BitBucket)

Doxygen がドキュメントを生成できるように，Doxyfile を作って置いておきます．詳しくはググって下さい．

Heroku

生成したドキュメントは Heroku に置かせてもらうことにしましょう．Heroku に登録し，アプリケーションを作っておきます．

Wercker

CI サービスには Wercker を使いましょう．GitHub/BitBucket 両方使えて，プライベートリポジトリもいけるので便利です．準備として，Wercker に登録して，アプリケーションを作成し，自分の GitHub/BitBucket リポジトリに接続しておきます．

wercker.yml

Wercker にやってもらうことは，リポジトリ直下の wercker.yml で指定します．テストなどを除いてドキュメントに関連がありそうな部分だけを取り出すと，以下のようになりました．

yaml

box: bendiken/cxx14@0.0.8
build:
  steps:
    - script:
        name: document
        code: |
          doxygen

deploy:
  steps:
    - script:
        name: installation
        code: |
          sudo apt-get update
          sudo apt-get install -y curl zip unzip
    - script:
        name: preparation
        code: |
          curl https://codeload.github.com/nulltask/heroku-static-provider/zip/master -o heroku-static-provider-master.zip
          unzip -o heroku-static-provider-master.zip
          cp -r html/* heroku-static-provider-master/public/
    - heroku-deploy:
        source_dir: heroku-static-provider-master/
        # cwd: heroku-static-provider-master/

ざっくり解説します．build では doxygen を実行します．deploy では，以下を行っています．

1. installation: まず必要なものをインストール．

2. preparation: Heroku にアップロードするディレクトリを用意．

   • Heroku に静的コンテンツを置くため，nulltask さんの heroku-static-provider を用意します．
   • html ディレクトリに生成された Doxygen ドキュメントをその中にコピー．

3. heroku-deploy: Wercker 公式 step の heroku-deploy を呼びます．

ちなみに:

• ビルドやテストも行いたい場合，build の steps に追加することになります．
• heroku-deploy で source_dir を使うと deprecated と言われるのですが，対応する機能は cwd で提供する予定とのことながらまだ提供されていないので，source_dir を使ってます．
• 今回は Doxygen のインストールされた box を使ってますが，box によっては Doxygen 自体のインストールが必要だと思います．

デプロイ設定

Wercker のアプリケーション設定で Deploy Target を追加し，Heroku API Key を登録する必要があります．

1. Wercker のアプリケーション設定を開きます．
2. Add deploy target で Heroku を選び，API Key を登録します．
3. Auto deploy に master とか書いておきます．

完成

Auto deploy に指定したブランチに push してしばらくすると，http://(名前).heroku.com にドキュメントが現れていることでしょう．めでたし！

Heroku から毎回 ssh key の追加の通知がきてウザい？

Wercker で ssh key を生成し，Heroku に登録します．

1. Wercker で ssh key を生成
2. Wercker の Deploy の設定で，ssh key を使う設定をします．
3. wercker.yml の heroku-deploy 下に key-name: (ssh key につけた名前) という行を追加します．
4. Heroku に公開鍵を追加します．