概要
ライブラリの動作確認をしているときにソースファイルを直接読むのがつらいのでDoxygenがあると便利なときがあると思います。どうせなら自動で作れるようにすると便利だと思い、連携方法を調べてみました。
テスト用リポジトリ作成
とりあえずあたらしく作って実験してみます。M5Unifiedを自動化したいのでフォークしようと思ったのですがPage公開が禁止設定されていたので、新規で作成して手動でコピーしてきます。
空のリポジトリができました。
M5UnifiedDoxygenTestのクローン
git clone git@github.com:tanakamasayuki/M5UnifiedDoxygenTest.git自分の環境にGitをクローンします。この段階では何もファイルが入っていません。
M5Unifiedのダウンロード
上記からZipで一式ファイルをダウンロードします。このファイルを展開して先程の空のリポジトリクローンにコピーします。この時点ではM5Unifiedとまったく同じファイル構成です。
アクション用ファイル追加
上記のアクションを利用させてもらいます。GitHub Actionからdoxygenを呼び出して、GitHub Pagesに連携してくれます。
- .github/workflows/doxygen-gh-pages.yml
上記ファイルを作成して、以下の設定を入れます。
mkdir .github
mkdir .github/workflows/
touch .github/workflows/doxygen-gh-pages.ymlとりあえずコマンドで空ファイルを作って書き換えます。
name: Doxygen GitHub Pages Deploy Action
on:
push:
branches:
- master
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: DenverCoder1/doxygen-github-pages-action@v1.3.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: gh-pages
folder: docs/html
config_file: Doxyfile最低限の設定ではなくAdvanced Usageの方を参考にしたほうがよいと思います。branchesがmainになっていますので、メインのブランチ名に変更してください。私はmasterを使っている事が多いです。
アクションのバージョンとかが上がっている可能性がありますので、定期的にバージョンを確認したほうがよいと思います。
あと、実行条件としてon pushでmasterが更新されたら毎回自動生成しています。このプロジェクトだと35秒ぐらいですが、大きなものだと無料枠を超過するので設定を調整したほうがよいと思います。on workflow_dispatchは手動実行の設定です。
Doxygenの設定ファイル作成
手で書くのは大変なので自分のパソコンにDoxygenをいれて、中に入っているウイザードを利用して設定ファイルを作ります。
このページで最低限設定するのはプロジェクト名と、ソースコードを「./」、フォルダのスキャンをチェック、出力先を「docs」にすることです。
とりあえずAll EntitiesにしてIncludeも追加するといろいろ対象ファイルが増えます。とりあえず全部入りにして、プログラム言語をC++にしました。
左パネルがあるナビゲーションに変更して、使わないLaTeXのチェックを外しました。
画像も内蔵のではなくGraphVizを利用して、全部入りで書き出します。
このページまで来たら完成なので、Save asで設定ファイルを書き出して、リポジトリに入れます。
アクションに書き込み権限追加
Setting -> Actions -> General -> Workflow permissionsでデフォルトの読み込みだけの権限から、書き込み権限も与えます。これで作成したDoxygenファイルを「gh-pages」ブランチに書き込むことができます。
ちなみにアクションに失敗して/usr/bin/gitのエラーがでるときには書き込み権限がない場合になります。Saveボタンで変更を保存しないと失敗します！
コミットとプッシュ
git add .
git commit
git push origin master上記を実行すると自動でアクションが動い、Doxygenのビルドが動くはずです。
成功すると「gh-pages」ブランチができています。このブランチにDoxygenが生成したファイルが入っています。
たくさんのファイルが入っていれば成功です。この状態だとまだPagesに公開されていませんので、公開設定をします。
Pages設定
公開するブランチを「gh-pages」にして/を設定します。Saveすることで設定完了です。ただし、即時反映ではないので数分待ちます。
リロードするとPagesのURLが増えていました。
上記になります。
たとえばこんな感じで関数のリファレンスと、その中で呼ばれているクラスなどがわかります。そして直接コードをみるリンクもあるので解析しやすくなります。
見た目の調整
最近は上記の設定をいれて、すこしモダンなDoxygenにするのがいいようです。みための問題なので、デフォルトのDoxygenは微妙だなという人は入れてみてください。
まとめ
GitHub Actionsは無料枠がある程度あるので、アカウントの枠に余裕があればドキュメントまで自動生成にしたほうが便利だと思います。ただし、pushをトリガーに自動生成しないで、workflow_dispatchで手動実行だけでも良いのかもしれません。もしくはreleaseとかのアクションかな？
コメント