Help us understand the problem. What is going on with this article?

iOSプロジェクトでApple風ドキュメントを自動生成する - jazzy -

More than 3 years have passed since last update.

先日、UIAlertControllerを便利に使うライブラリALRTを公開しました!

【Swift】UIAlertControllerをもっと便利にするALRTを作りました

ドキュメントもしっかり作ってみようと、Realm製のiOSプロジェクト向けドキュメント自動生成ツール jazzyを試してみたところ、かなりお手軽にそれらしいドキュメントを作ることができました。

コメント入りの自作ライブラリをCocoapodsにPushすると、Cocoadocsというドキュメントページが自動作成されますが、その裏ではjazzyが動いています

この記事では、Cocoapodsに自作ライブラリを投稿しない人でも、iOSプロジェクトでドキュメントを自動作成できるよう流れを共有します。

完成図

まず、肝心のどんなドキュメントができるかについてですが、以下のようなApple風ドキュメントを作ることができます。

Cocoadocsになりますが、有名ライブラリだと、APIKitAlamofireのドキュメントページもjazzyで作られています。

手順

1. Xcodeプラグイン Alcatrazをインストール

Xcodeプラグインマネージャー Alcatrazをインストールします。
以下のInstallコマンドをterminalで入力すればOKです。終了したら、Xcodeを再起動してください。

Alcatraz公式サイト

curl -fsSL https://raw.githubusercontent.com/supermarin/Alcatraz/deploy/Scripts/install.sh | sh

2. VVDocumenterをインストール

コメント入力を劇的に楽にしてくれるプラグインVVDocumenterをここでは使います。まずは、Xcode -> Window -> Package Managerで、Alcatrazを起動します。

Screen Shot 2016-08-08 at 22.39.44.png

次に、AlcatrazでVVDocumenterを検索し、インストールします。終わったらXcodeを起動してください。再起動時にプラグインを読み込むか聞かれるので、Load Bundleを選んでください。

Screen Shot 2016-08-08 at 22.39.56.png

3. コメントを入れる

VVDocumenterを使って、コメントを入れていきましょう。
クラス宣言や、メソッドの上で///と入力すると、自動でコメントフォーマットを補完してくれます。
あとは、自分でパラメーターや、返り値の説明や型などを入力していきます。
クラスやメソッドは、publicにしないと、後々ドキュメントに反映されないので注意が必要です。

import UIKit

/// 普通のViewControllerです

public class ViewController: UIViewController {
    /**
     至って普通のViewDidLoadです
     */
    override public func viewDidLoad() {
        super.viewDidLoad()
    }

    /**
     2つのIntを足し算します。

     - parameter x: Int型の値
     - parameter y: Int型の値

     - returns: Int
     */

    public func addTwoInts(x: Int, y: Int) -> Int {
        return x + y
    }
}

4. Gemでjazzyをインストール

jazzyをGem経由でインストールします。
一応、Gemをアップデートしておきましょう。

gem update
gem install jazzy

5. jazzyを使ってみる!

Xcodeプロジェクトのルートで、以下のようなjazzyコマンドを入力すると、ドキュメントファイルが生成されます。

jazzy --author 作者名 --author_url 作者URL -o 出力パス

その中のindex.htmlをブラウザなどで開いてみると先ほどのコメントが反映されたドキュメントページができあがっているのがわかります。

番外編:公開

できあがったファイルはGithub Pagesに置くと、ドキュメントサイトとして公開可能です。もちろん自前でホストしても構いません。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした