はじめに
- 前回の投稿で自作のFrameworkを作成し、実際に使用する所までの手順を確認しました。今回は、Frameworkを言えばドキュメントだよね、という事で、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
-
Objective-C
それぞれ、参考の資料を見てとの事です。安定の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の設定はこちらです。
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つです。
ここから、サンプルを確認することができます。
お好みで使い分ける事ができそうですね。
また、--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`
こんな感じで、ドキュメントが生成されます。
Frameworkをビルドするタイミングで、ドキュメントを生成する
前回同様、Run Scriptでスクリプトを追加する方法をとります。
- 完成したものがこちらになります。
感想
これで、継続的ドキュメント生成が可能になりました。コンテキストによっても、ベストプラクティスがあるかと思いますので、是非よい知見があれば教えていただけるとうれしいです。