gcovr や Doxygen の HTML を自動的に deploy する
やりたいこと
- GitHub のリポジトリ上のものを種に生成される静的 HTML サイトを自動的に deploy する
- Doxygen で生成した HTML
- gcovr で生成した Coverage report の HTML
- ...
GitHub Actions で actions/upload-artifact
を使えば
ディレクトリ単位の成果物を workflow の実行に紐付けてアップロードするのは簡単にできるのだが、
ディレクトリごとの ZIP ファイルになってしまうので
いちいちダウンロードして解凍しないとブラウザで確認できない。
これはちとめんどくさい。
どこかのサイトに自動的にアップロードされて、 必要に応じて自動的に更新されると嬉しいなー、と。
道具
- GitHub Pages
- deploy 先として使う
- あらかじめ設定しておいたブランチに push さえすれば、その内容を https://username.github.io/repository_name/ というサイトとして見られるように deploy できる仕組み
- GitHub Actions
- GitHub 謹製の CI/CD システム
- 静的 HTML サイトの構成を作って deploy するのに使う
peaceiris/actions-gh-pages
- 「あらかじめ設定しておいたブランチに push」をやってくれる GitHub Actions の action
下準備
- リポジトリの Settings で GitHub Pages の設定を
gh-pages
ブランチを deploy するように設定しておく- あとからやってもいいが、 push 時にしか deploy されないみたいなので、あとから設定した場合は設定後一度 push する必要があるっぽい
解説
- 2020/09/06 時点での GitHub Actions の workflow は https://github.com/MinoruSekine/libfixedpointnumber/blob/9085595bb0848fb1bcb7f634f1af63e8d2383ee6/.github/workflows/deploy_github_pages.yml
- 読んで分かることしかしてないけど、以下パートごとに解説
master
ブランチへpush
時にこの workflow が動くようにする、PRマージ時もこれで動く、ついでにworkflow_dispatch:
を書いておいてデバッグ等で便利なように手動トリガー可能にしておく
on: push: branches: - master workflow_dispatch:
runs-on
は https://github.com/peaceiris/actions-gh-pages にどれをサポートしているか書いてあるのでその中から選ぶ
jobs: deploy: runs-on: ubuntu-18.04
- チェックアウトする
steps: - uses: actions/checkout@v1
- 静的HTMLサイトを生成するのに必要な道具をセットアップする
- ここは Pelican でも何でもお好みのツールをセットアップすればOK
- この例では coverage report のための gcovr と Google Test Framework、Doxygen ドキュメントのために Doxygen と GraphViz をインストールしてる
- 最後の
rm -rf googletest
はmake install
するために checkout してきたソースコードとビルド生成物を消してる- これをやっておかないと
googletest/
以下の Doxygen とか作ろうとしちゃう /tmp/
とかへ checkout するなり、Doxyfile
で exclude するなりすればいいのだが、手を抜いてるだけ
- これをやっておかないと
- name: Install gcovr run: | sudo pip3 install gcovr - name: Install graphviz and doxygen run: | sudo apt update sudo apt install -y --no-install-recommends graphviz doxygen - name: Install googletest run: | git clone https://github.com/google/googletest.git cd googletest cmake -DBUILD_GMOCK=OFF -DCMAKE_CXX_STANDARD=11 . sudo make -k -j all install cd .. rm -rf googletest
- 静的HTMLサイトを生成する、この例では
make site
でout/site/
以下に静的HTMLサイトが生成されるようにしてある ( https://github.com/MinoruSekine/libfixedpointnumber/blob/9085595bb0848fb1bcb7f634f1af63e8d2383ee6/Makefile#L216 )
- name: Build site run: | make BUILD_TYPE=coverage -k -j site
- Deploy する、
publish_dir
以下が deploy される- 実際にはリポジトリの
gh-pages
というブランチに push されるだけ
- 実際にはリポジトリの
- name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./out/site
できあがったサイト
- 以上で、 PR マージなどで
master
ブランチが更新されるたびに静的 HTML サイト(Doxygen ドキュメントと coverage report)が更新される - というわけで出来上がったのが minorusekine.github.io