apigenでGitHubにAPIドキュメントページを作成する

MauticommerceプラグインのAPIリファレンスをざっと作ってみました。
https://amimoto-ami.github.io/mauticommerce/

apigenというツールとGitHub Pagesを利用することで、非常に簡単に作ることができたので、覚書としてまとめます。

apigenのインストール

apigenはphpdoc形式で記述したコードをAPIリファレンス化してくれるツールです。
https://www.apigen.org/

ドキュメントにインストール方法が記載されていますが、以下の手順で簡単にインストールすることができます。

$ wget https://apigen.org/apigen.phar
$ chmod +x apigen.phar
$ mv apigen.phar /usr/local/bin/apigen
$ apigen --version

apigenでドキュメント作成

GitHub Pagesは、docsディレクトリに配置したHTMLが利用可能です。
*Mauticommerceの場合はこのようになっています。

ということで、apigenで生成するファイルをdocsディレクトリに出力するようにしましょう。

$ cd /PATH/TO/YOUR/PLUGIN/DIR
$ apigen generate --source ./ --destination docs

これでphpdocsに記述したコメントを元にリファレンスが作成されました。
あとはgit commit -m "add apigen docs" && git push origin masterのような形でGitHubへ 反映させましょう。

GitHub Pagesを作る

あとはリポジトリの「Settings」からGitHub Pagesを作成します。

Sourceの中に/docs folderという項目がありますので、それを選択しておきましょう。

ここまでできれば、あとはページの生成完了まで５分程度待機するだけです。

まとめ

phpdocsでのコメントを書いている場合、apigen + GitHub Pagesでかなり簡単にドキュメントページを作れます。
phpdocsを書くだけでも実装内容の整理などができますので、この機会に是非お試しください。