Xcode7.3 & SwiftでつくるCocoaTouch Framework（jazzy - ドキュメント生成編）


<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/4fd247a5-d9f7-13a6-c999-3d9dafcc9003.jpeg" width="480">

# はじめに

- [前回の投稿](http://qiita.com/mfks17/items/e95bdd79ea24cdd2391c)で自作のFrameworkを作成し、実際に使用する所までの手順を確認しました。今回は、Frameworkを言えばドキュメントだよね、という事で、[jazzy](https://github.com/realm/jazzy)を調査を兼ねて触って、ドキュメントを生成できればと思います。

# 環境

- OS X El Captian 10.11.4
- Xcode 7.3
- Swift 2.0
- ruby 2.0.0p648 (2015-12-16 revision 53162) [x86_64-darwin15.4.0]
- gem 2.0.14.1
- jazzy version: 0.6.2

## jazzyとは

>
jazzy is a command-line utility that generates documentation for Swift or Objective-C

## jazzyのインストール

```[sudo] gem install jazzy```

ちなみに、Rubyはrbenvで入れたRuby2.0.0でgemコマンドを実行しています。

## 使用方法

ターミナルから```jazzy```で実行する事ができます。```jazzy -h```でオプションのリストを確認することができます。
```.jazzy.yml```という設定ファイルを作成しておく事で、```jazzy -help```でしめされる設定を定義する事ができます。

## サポートしているキーワード

- Swfit
	- [Swift header documentation in Xcode 7](http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/)

- Objective-C
	- [HeaderDoc User Guide](https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html)

それぞれ、参考の資料を見てとの事です。安定のERICA様

## 使用例

ここからは、Swiftの設定がDefaultで話しを進めます。

まずは、```jazzy -h```の結果をみてみましょう。

```
Usage: jazzy

Options
    -o, --output FOLDER              Folder to output the HTML docs to
    -c, --[no-]clean                 Delete contents of output directory before running.
                                     WARNING: If --output is set to ~/Desktop, this will delete the ~/Desktop directory.
        --[no-]objc                  Generate docs for Objective-C.
        --umbrella-header PATH       Umbrella header for your Objective-C framework.
        --framework-root PATH        The root path to your Objective-C framework.
        --sdk [iphone|watch|appletv][os|simulator]|macosx
                                     The SDK for which your code should be built.
        --config PATH                Configuration file (.yaml or .json)
                                     Default: .jazzy.yaml in source directory or ancestor
    -x arg1,arg2,…argN,              Arguments to forward to xcodebuild
        --xcodebuild-arguments
    -s FILEPATH,                     File generated from sourcekitten output to parse
        --sourcekitten-sourcefile
        --source-directory DIRPATH   The directory that contains the source to be documented
    -e, --exclude file1,file2,…fileN Files to be excluded from documentation
        --swift-version VERSION
    -a, --author AUTHOR_NAME         Name of author to attribute in docs (e.g. Realm)
    -u, --author_url URL             Author URL of this project (e.g. http://realm.io)
    -m, --module MODULE_NAME         Name of module being documented. (e.g. RealmSwift)
        --module-version VERSION     module version. will be used when generating docset
        --copyright COPYRIGHT_MARKDOWN
                                     copyright markdown rendered at the bottom of the docs pages
        --readme FILEPATH            The path to a markdown README file
        --podspec FILEPATH
        --docset-icon FILEPATH
        --docset-path DIRPATH        The relative path for the generated docset
    -r, --root-url URL               Absolute URL root where these docs will be stored
    -d, --dash_url URL               Location of the dash XML feed e.g. http://realm.io/docsets/realm.xml)
    -g, --github_url URL             GitHub URL of this project (e.g. https://github.com/realm/realm-cocoa)
        --github-file-prefix PREFIX  GitHub URL file prefix of this project (e.g. https://github.com/realm/realm-cocoa/tree/v0.87.1)
        --skip-documentation         Will skip the documentation generation phase.
        --min-acl [private | internal | public]
                                     minimum access control level to document
        --[no-]skip-undocumented     Don't document declarations that have no documentation comments.
        --[no-]hide-documentation-coverage
                                     Hide "(X% documented)" from the generated documents
        --head HTML                  Custom HTML to inject into <head></head>.
        --theme [apple | fullwidth | DIRPATH]
                                     Which theme to use. Specify either 'apple' (default), 'fullwidth' or the path to your mustache templates and other assets for a custom theme.
    -t, --template-directory DIRPATH DEPRECATED: Use --theme instead.
        --assets-directory DIRPATH   DEPRECATED: Use --theme instead.
    -v, --version                    Print version number
    -h, --help [TOPIC]               Available topics:
                                       usage   Command line options (this help message)
                                       config  Configuration file options
                                     ...or an option keyword, e.g. "dash"
```
上記の中から、自分の環境にあった設定を構成して、ドキュメントを生成していく感じですね。

実際にRealmさんで使用している設定はこちらです。

```
jazzy \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --xcodebuild-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --theme docs/themes
```

ちなみに、```Objective-C```を設定する際は

- --objc
- --umbrella-header ...
- -framework-root ...
- --sdk [iphone|watch|appletv][os|simulator]|macosx (optional, default value of macosx)

を明示的にパラメータを追加する必要があります。

また、RealmさんでのObjective-Cの時の設定は以下です。

```
jazzy \
  --objc \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --umbrella-header Realm/Realm.h \
  --framework-root . \
  --module Realm \
  --root-url https://realm.io/docs/objc/0.96.2/api/ \
  --output docs/objc_output \
  --theme docs/themes
```
著名なネットワーキングライブラリである[AFNetworking](https://github.com/AFNetworking/AFNetworking)の設定はこちらです。

```
jazzy \
  --objc \
  --author AFNetworking \
  --author_url http://afnetworking.com \
  --github_url https://github.com/AFNetworking/AFNetworking \
  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
  --module-version 2.6.2 \
  --umbrella-header AFNetworking/AFNetworking.h \
  --framework-root . \
  --module AFNetworking
```

なんとなく、感じがつかめてきたでしょうか。

## テーマについて

jazzyでは２つのテーマについて対応しているようで、それは```apple```(default), ```fullwidth```の2つです。

ここから、サンプルを確認することができます。

- [https://realm.io/docs/swift/latest/api/ :apple](https://realm.io/docs/swift/latest/api/)


<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/d6fe8828-d9fa-1274-cd7a-ab692049a40f.png" width="600">


- [http://reduxkit.github.io/ReduxKit/ :fullwidth](http://reduxkit.github.io/ReduxKit/)

<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/e3893d92-f448-b9c2-e36a-a0874276201a.png" width="600">

お好みで使い分ける事ができそうですね。
また、```--theme```オプションを渡すことによって、使用するテーマを指定することができます。
あなたのテーマディレクトリへのパスを渡すことで、独自のカスタムテーマを提供することができます。

## 実際に使ってみる

- まずは、ドキュメントを生成するプロジェクトのディレクトリに移動します。

```$ cd <project root>```

- ドキュメントの吐き出し先のディレクトリを生成します。

```$ mkdir document```

- 実際にコマンドを実行してみる

```
$ jazzy -o document
Running xcodebuild
Parsing Ditto.swift (1/1)
building site
jam out ♪♫ to your fresh new docs in `document`
```

こんな感じで、ドキュメントが生成されます。

<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/b6523738-ff8a-4924-8e26-a216bb5d782b.png" width="280">

## Frameworkをビルドするタイミングで、ドキュメントを生成する

前回同様、```Run Script```でスクリプトを追加する方法をとります。

<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/c061fe8d-d7ce-5190-ea2f-2954b6128af4.png" width="480">

- https://gist.github.com/mfks17/999a7d2629797fc65124d3ee1d9109e4

<img src="https://qiita-image-store.s3.amazonaws.com/0/25250/6d0ee52c-48b4-fd30-891d-72947fe4c7d0.png" width="600">

- 完成したものがこちらになります。

# 感想

これで、継続的ドキュメント生成が可能になりました。コンテキストによっても、ベストプラクティスがあるかと思いますので、是非よい知見があれば教えていただけるとうれしいです。

# 謝辞

- [Github - jazzy](https://github.com/realm/jazzy)
- [クールなSwift用ドキュメントジェネレーターjazzyを使った](http://blog.euphonictech.com/entry/2015/03/28/215836)
- [Swiftでヘッダドキュメント](http://d.hatena.ne.jp/tsntsumi/20140809/HeaderDocumentationInSwift
)
- [Swift Documentation](http://nshipster.com/swift-documentation/)
- [jazzyを使って、Swiftで書いたプロジェクトのリファレンスを自動生成しよう！](http://grandbig.github.io/blog/2016/01/12/jazzy/)
- [Swift header documentation in Xcode 7](http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/)
- [HeaderDoc User Guide](https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html)