jazzyの使い方 その1

Swiftのドキュメント生成ツールのjazzyの使い方。 その1はコマンド周りのメモ

ドキュメント生成時のコマンド

主に自分個人で使う時のコマンドは以下の通り

jazzy -o Documents --min-acl internal --skip-undocumented -a M.Ike -x SYMROOT=/private/tmp/jazzy

”-o Documents”

-o [フォルダ]でドキュメントを出力するフォルダを指定する
なお、フォルダが存在しない場合は自動で作成される

今回の指定だと以下の場所にフォルダが生成される

Sample                 # 対象のプロジェクトのフォルダ
  ├─ Sample            # Xcodeのソースなど一式
  ├─ Sample.xcodeproj  # Xcodeのプロジェクトファイル
  └─ Documents         # この中に生成されたドキュメント一式が入る

”–min-acl internal”

--min-acl [private | internal | public]で出力の対象を指定する

Swift2.xではpublicは使わずに、明示的なprivateか暗黙的なinternalしか使わない (※ライブラリではない通常のソースの場合)ので、internal以上で設定している

”–skip-undocumented”

この設定をすると、ドキュメントコメントのないソースからはドキュメントを生成しなくなる

さらにdocumentation-coverageの対象からも除外される

”-a”

作者名の指定。別に個人用なので必要もないが、ないと見栄えが悪いのでつけている

”-x SYMROOT=/private/tmp/jazzy”

-x arg1,arg2,…argN,xcodebuild時のビルドオプションを指定できる

jazzyを使うとbuildというビルドの一時ファイルの入ったディレクトリが プロジェクトのフォルダ内に生成されてしまう

.gitignoreでちゃんと指定しているので実害はないが、一時ファイルが生成されるのは気持ち悪い。。。

という訳で、これを指定すればjazzy利用時の一時ファイルを /private/tmp/jazzy(テンポラリフォルダ)へ出力させることができ、 同じフォルダ内にbuildフォルダが生成されなくなる (テンポラリフォルダは再起動時に消去される)

ただしXcodeのプロジェクトの設定によっては、別の環境変数を書き換える必要あり

使っていないもの

-cをつけると、ドキュメント作成前に元のデータを全部消してくれるので、 本来はつけておいた方が良いオプション

が、ヘルプにもあるように、指定した出力先のフォルダが問答無用で削除されてしまう。。。
開発中はターミナルから手打ち(コピペ)して使うことが多いので、 間違って指定してしまった!という悲劇を防ぐ為、これは指定していない

(確実に作りたい時は手動で削除で対応 ビルド用のシェルスクリプトを組んでいる場合はつけている)

開発環境