Swiftのドキュメンテーションコメントをjazzyで出力

Swiftのフレームワークを作っていて、コメントからドキュメントを吐き出す必要に迫られたので、いろいろ調べていましたが、Rubyライブラリのjazzyというgemを使えばよさそうだなというところまで辿りつきました。

Ruby環境の構築

まずは、Rubyの環境を整えるところから。rbenvを入れるところからです。

$ brew update
$ brew install rbenv ruby-build

$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

$ source ~/.bash_profile
$ rbenv --version

続いて、Rubyのインストール。ここでは2.3.0をインストールしています。インストールは5～10分くらいかかる感じです。

$ rbenv install --list
$ rbenv install 2.3.0

で、インストールしたバージョンの選択。

$ rbenv global 2.3.0

jazzyのインストール

jazzyのインストールは、gemで一発です。

$ sudo gem install jazzy

実際にjazzyでドキュメントを吐き出してみる

jazzy --min-acl public --skip-undocumented -o jazzy_doc --swift-version 2.1.1

今回はフレームワークの出力なので、出力レベル(--min-acl)はpublicです。これを指定すると、internalやprivateのメソッドは出力されません。あと、--skip-undocumentedで、ドキュメントのないソースは無視するっぽいです。-oで出力先を指定します。

ここで落とし穴

• 実行するパスは *.xcodeprojのあるディレクトリでないといけない
• Xcodeが最新バージョンでない場合、swiftのバージョンを指定する必要がある。

現場からは以上です。

参考

http://dev.classmethod.jp/server-side/language/build-ruby-environment-by-rbenv/
http://grandbig.github.io/blog/2016/01/12/jazzy/