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 する必要があるっぽい

解説

on:
  push:
    branches:
      - master
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-18.04
  • チェックアウトする
    steps:
    - uses: actions/checkout@v1
  • 静的HTMLサイトを生成するのに必要な道具をセットアップする
    • ここは Pelican でも何でもお好みのツールをセットアップすればOK
    • この例では coverage report のための gcovr と Google Test Framework、Doxygen ドキュメントのために DoxygenGraphViz をインストールしてる
    • 最後の rm -rf googletestmake 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
    - 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