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

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

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

apigenのインストール

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

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

$ wget http://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を作成します。
%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-2016-11-10-23-40-28
Sourceの中に/docs folderという項目がありますので、それを選択しておきましょう。

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

まとめ

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

Follow me!

Okamoto Hidetaka
デジタルキューブのインフラエンジニア。勉強会に和太鼓の練習から直行することが多く「太鼓の人」とかよばれてます。 思いつきで公式ディレクトリにテーマやプラグインをアップしたりテーマレビューやったりしています。 AWS / WordPress / LinkedOpenData周りで活動していて、APIをどうこうして何か作るというのが多いです。 ひとこと
mautic is open source marketing automation