S 프로젝트에서 Apple 스타일 문서 자동 생성 - jazzy -

요 전날 UIALertController를 편리하게 사용하는 라이브러리 ALRT를 공개했습니다!

【Swift】UIAlertController를 보다 편리하게 하는 ALRT를 만들었습니다

문서도 제대로 만들어 보려고 Realm의 iOS 프로젝트 용 문서 자동 생성 도구 jazzy를 시도해 보니 꽤 쉽게 이러한 문서를 만들 수있었습니다.

코멘트가 있는 자작 라이브러리를 Cocoapods에 Push하면, Cocoadocs라는 문서 페이지가 자동 작성됩니다만, 그 뒤에서는 jazzy가 움직이고 있습니다.

이 기사에서는 Cocoapods에 자체 제작 라이브러리를 게시하지 않은 사람이라도 iOS 프로젝트에서 문서를 자동으로 만들 수 있도록 흐름을 공유합니다.

완성도

우선, 중요한 문서를 할 수 있는 것에 대해입니다만, 이하와 같은 Apple풍 문서를 만들 수 있습니다.

Cocoadocs가 되지만, 유명 라이브러리라면, APIKit나 Alamofire의 문서 페이지도 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를 시작합니다.



그런 다음 Alcatraz에서 VVDocumenter를 찾아 설치합니다. 완료되면 Xcode를 시작합니다. 다시 시작할 때 플러그인을 읽거나 들으려면 Load Bundle를 선택하십시오.

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에 넣으면 문서 사이트로 게시할 수 있습니다. 물론 스스로 호스팅해도 괜찮습니다.