jazzyでSwiftからドキュメント作成

jazzyを入れるためにrubyを入れるためにrbenvを入れるためにまずHomebrewをインストール。

環境
OS:Sierra
IDE:XCode8.0
Language:Swift2.3

jazzyとは

https://github.com/realm/jazzy
jazzy is a command-line utility that generates documentation for Swift or Objective-C
objCやSwiftのドキュメントコメントからコマンドラインでドキュメントを生成することができます。

rubyがインストールされていればターミナルで

sudo gem install jazzy

と入力することでjazzyをインストールできます。
ただしMacに標準に入っているRuby2.0.0は未対応のようでRuby2.2.2以降が必要になります(2016/10/18現在)

ERROR: Error installing jazzy:
activesupport requires Ruby version >= 2.2.2.

Rubyのインストール

http://media.tech-salon.com/ruby-%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB-mac/

homebrewのインストール
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

passwordを聞かれたら現在ログイン中のユーザパスワードを入力。

==> Installation successful!
==> Next steps

と表示されたらOK。

インストールされているか確認します。

brew doctor

Your system is ready to brew.
と表示されたらOK。

一応最新へアップデート（新規に入れたなら必要ない）

brew update

rubyの管理ツールrbenvをインストール

brew install ruby-build
brew install rbenv

インストール可能なrubyをリスト表示
rbenv install -l

Ruby2.3.1をインストール

rbenv install 2.3.1

ざっと見た感じ2.3.1(最新バージョン)で問題なさげ

使用するバージョンを切り替え

以下のパス設定をしておかないとrubyのバージョンが切り替わらないので注意

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
echo 'eval "$(rbenv init -)"' >> .bash_profile
source .bash_profile

rbenv global 2.3.1

Rubyのバージョン確認

ruby -v

ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin16]
と表示されていたら問題なし

jazzyインストール

http://qiita.com/mfks17/items/13992dbe8530c069d3a7

sudo gem install jazzy

jazzy -h

でヘルプが表示されたらインストール成功
プロジェクトのルート(XXXX.xcodeprojがあるディレクトリ)でjazzyコマンドを入力することでドキュメントを出力することができるようになります。

jazzyでドキュメント出力

デフォルトでは出力されるのはpublicのみなので以下のコマンドだと何も出力されません(ここでハマった)

jazzy -o document

理由はXcodeからSwiftのファイルを作成した場合デフォルトのアクセス修飾子がinternalになっているためです。

internalなクラス・メソッドも出力対象にするには以下を追加します。
--min-acl internal

jazzy --min-acl internal -o document

これで出力されるようになります。

jazzyのオプション

以下はjazzy -hでも確認できます。

短縮系と通常のオプションがあり
-o directory
--output directory
は同じ意味になります。

-o [出力先]
出力先を指定します。

-c
出力前に出力先を削除するようです。

-x arg1, arg2
ビルド時引数とのことだがいまいちわからない
失敗する場合はこの辺りを指定する必要あり？

-s FILEPATH
ソースがあるパスかな？
指定しない場合プロジェクトルート以下のすべてのソースが対象になります。

-a AUTHOR_NAME
作成者の名前を入れたりする

-u url
githubとかプロジェクトのURLを入れたりするんだろうか？

-m MODULENAME
モジュール名、バージョン、コピーライトなどを記述するらしい

objCのソースを出力対象にする
--objc
--umbrella-header ...
-framework-root ...
--sdk [iphone|watch|appletv][os|simulator]|macosx (optional, default value of macosx)

構成が複雑だとうまく出力されなかったりするので少し考慮が必要かも