[iOS][Swift] 「Jazzy」を使ってSwiftのソースファイルからドキュメントを生成する

2018.03.19

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは。加藤です。「Jazzy」。その存在は前から知ってはいたものの、実際に使用する場面が無く、これまで使ったことはありませんでした。しかしながら今回使う機会がありましたので忘れないように記録に残しておきます。

Jazzyとは

Jazzyとは、SwiftやObjective-Cのドキュメントを生成するツールです。
以下はリポジトリREADMEからの引用です。

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

モバイルデータベースで有名なRealmによって管理されており、MITライセンスで公開されています。

検証環境

本エントリは以下の環境で検証を行っています。

  • macOS High Sierra バージョン 10.13.3
  • Xcode Version 9.2 (9C40b)
  • Swift 4
  • Jazzy 0.9.1
  • CocoaPods 1.3.1

ここではあるiOSアプリを作成していて、ライブラリ管理にはCocoaPodsを使用しているとしましょう。 プロジェクト名は今回「JazzySample」としました。 CocoaPodsでライブラリをインストールすると、以下のようにxcworkspaceファイルが生成されているでしょう。

ソースファイル

今回はドキュメント生成結果を確認するために、以下のファイルを作成しました。

UserRepository.swift

import Foundation

/// ユーザーのリポジトリ
class UserRepository {

    /// IDを指定してユーザーを取得する。
    ///
    /// - Parameter identifier: ユーザーID
    /// - Returns: ユーザー
    func find(byIdentifier identifier: String) -> User {
        // TODO: impl
        return User(identifier: "1", name: "kato")
    }

    /// プライベート関数
    private func pFunc() {
    }
}

User.swift

import Foundation

/// ユーザー
struct User {

    /// ID
    let identifier: String

    /// 名前
    let name: String
}

使ってみた

Jazzyのインストール

以下のコマンドを実行してインストールします。

[sudo] gem install jazzy

jazzy -h でオプションの説明が見れる

jazzyには非常に豊富な実行オプションがあるため、 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.
        --hide-declarations  
                                     Hide declarations in the specified language. Given that generating Swift docs only generates Swift declarations, this is only really useful to display just the Swift declarations & names when generating docs for an Objective-C framework.
        --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 filepath1,filepath2,…filepathN,
        --exclude                    Source file pathnames to be excluded from documentation. Supports wildcards.
        --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
        --documentation GLOB         Glob that matches available documentation
        --abstract GLOB              Glob that matches available abstracts for categories
        --podspec FILEPATH           A CocoaPods Podspec that describes the Swift library to document
        --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)
        --disable-search             Avoid generating a search index. Search is available in some themes.
        --skip-documentation         Will skip the documentation generation phase.
        --min-acl [private | fileprivate | internal | public | open]
                                     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.
        --use-safe-filenames         Replace unsafe characters in filenames with an encoded representation. This will reduce human readability of some URLs, but may be necessary for projects that expose filename-unfriendly functions such as /(_:_:)
    -t, --template-directory DIRPATH DEPRECATED: Use --theme instead.
        --assets-directory DIRPATH   DEPRECATED: Use --theme instead.
        --undocumented-text UNDOCUMENTED_TEXT
                                     Default text for undocumented symbols. The default is "Undocumented", put "" if no text is required
    -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"

コマンドラインで生成する

まずは基本。コマンドラインで生成してみましょう。以下のコマンドをプロジェクトのルートディレクトリで実行してみました。

jazzy --min-acl internal \
-c  \
-o docs \
--author kato  \
--author_url https://dev.classmethod.jp/ \
--module JazzySample \
--xcodebuild-arguments -workspace,JazzySample.xcworkspace,-scheme,JazzySample

以下、オプションの説明です。

  • min-ac
    • minimum access control level。[private | fileprivate | internal | public | open]
    • ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
  • c
    • 実行前に出力先フォルダをクリーンする。
  • o
    • ドキュメント出力先フォルダの指定
  • author
    • 著者
  • author_url
    • 著者のURL
  • module
    • ドキュメント化するモジュールの名前
  • xcodebuild-arguments
    • xcodebuildへ渡すパラメータ。カンマ区切りで指定する。

結果はこちら。htmlやらjsonが生成されました。

index.htmlを開いてみましょう。
おぉ、ちゃんとドキュメント生成されてますね〜!! 今回はmin-acinternalを指定したのでprivateな関数はドキュメントに含まれていないですね。すごい。

設定ファイルを用意して生成する

上述のようにコマンドラインでオプションを指定して実行できますが、別途オプションを記載したyamlファイルを用意して実行することもできます。 指定するオプションが多い場合や、設定ファイルもgit等で管理したい場合はyamlファイルを使用した方が良いでしょう。 デフォルトで、.jazzy.yamlというファイルを用意しておけば設定を読み込んでくれるようになっています。

コマンドラインで実行した内容を.jazzy.yamlにしたものが以下です。

.jazzy.yaml

# minimum access control level。[private | fileprivate | internal | public | open]
# ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
min_acl: internal

#実行前に出力先フォルダをクリーン
clean: true

# ドキュメント出力先フォルダ
output: docs

# 著者
author: kato

# 著者のURL
author_url: https://dev.classmethod.jp

# ドキュメント化するモジュールの名前
module: JazzySample

# xcodebuildの引数
xcodebuild_arguments: [-workspace,JazzySample.xcworkspace,-scheme,JazzySample]

.jazzy.yamlをプロジェクトのルートディレクトリに配置し、jazzyコマンドを実行します。
以下のように.jazzy.yamlの設定を使用してドキュメントを生成してくれます。

まとめ「めちゃめちゃ便利なドキュメント生成ツール」

簡単にドキュメント生成できて、オプションも豊富で、設定ファイルに記述できて、もうめちゃめちゃ便利ですね。 生成されるモジュールが複数あるプロジェクトの場合はモジュール名を忘れずに指定するようにしてください。 うまくドキュメントが生成されない場合は、まずxcodebuild単体で実行してみるといいと思います。
xcodebuildが成功するかどうかでxcodebuild_argumentsの指定が正しいかどうかの切り分けができるのでお試しください。

参考記事