Jazzy로 프로젝트 래퍼런스 문서 만들기

Jazzy로 프로젝트 관리 문서 만들어보기

포스팅 시간 기준 아래 버전들로 테스트 하였습니다.

( MacOS Catalina 10.15.7, Xcode 12.4 Build version 12D4e)
$ gem --version
3.2.22

$ jazzy -verison
jazzy version: 0.14.2

---

Jazzy란

개발하고 있는 프로젝트에 대한 스펙 문서를 만들려고 하다 보니 어디부터 시작해야 할지 몰라서 여기저기 찾아보던 중

좋은 오픈소스가 있어서 공유하고자 합니다.

jazzy 라는 CLI툴은 Swift/Objective-C로 되어있는 프로젝트를 빌드한 결과를 가지고 Document를 만들어줍니다.

그래서 현재 프로젝트가 xcodebuild로 빌드가 되어야 결과물이 생성 됩니다.

---

Jazzy 설치

jazzy는 ruby패키지로 아래 명령어로 설치를 할 수 있습니다.

만약 gem관련 에러가 발생한다면 Ruby gem error를 참고하시기 바랍니다.

$ gem install jazzy

---

Jazzy 실행

실제 Xcode 프로젝트가 있는 폴더로 이동 합니다.

$ pwd
/Users/hgkwon/TestProject
$ ls
TestProject TestProject.xcodeproj TestProjectTests TestProjectUITests build

기본적으로 Jazzy는 public/open 선언부의 함수들만 문서로 만들어주기 때문에 –min-acl 옵션을 통해 낮은 레벨까지 출력하도록 해줍니다.

Jazzy by default documents only public and open declarations. 
To include declarations with a lower access level, 
set the --min-acl flag to internal, fileprivate, or private.

$ jazzy --clean --min-acl internal (clean 옵션은 docs 삭제 옵션)
Running xcodebuild
Checking xcodebuild -showBuildSettings
Assuming New Build System is used.
Parsing AppDelegate.swift (1/4)
Parsing TestClass.swift (2/4)
Parsing TestStruct.swift (3/4)
Parsing ViewController.swift (4/4)
0% documentation coverage with 15 undocumented symbols
included 15 internal, public, or open symbols
skipped 1 private or fileprivate symbol (use `--min-acl` to specify a different minimum ACL)
building site
building search index
jam out ♪♫ to your fresh new docs in `docs`

결과는 아무런 내용없이 함수 원형만 있는데.. Swift에서 사용하는 Markdown 형태의 주석을 추가해주면

실제 Apple스러운 문서를 만들 수 있습니다.

참고) Apple Markup Essentials

아 그리고 저처럼 import Foundation 위에 주석을 작성하여 계속 Undocumented를 보는 사람은 없기를 바랍니다.

Class 설명 주석은 import후에 아래와 같이 class선언부 위에 작성해야합니다.

아래는 테스트 코드 원문입니다.

---

Jazzy Errors

Build Failed - no such module

Xcode에서 빌드도 잘되고 실행도 잘 되는데.. jazzy 명령어로 실행할때 에러가 발생하고

에러 로그를 찾아보면 no such module이라는 에러가 발생하는 경우가 있습니다.

pb.swift:11:8: error: no such module 'SwiftProtobuf'
import SwiftProtobuf
       ^
** BUILD FAILED **

The following build commands failed:
	CompileSwift normal x86_64
	CompileSwiftSources normal x86_64 com.apple.xcode.tools.swift.compiler
(2 failures)

해당 에러가 발생하면 현재 프로젝트가 워크스페이스로 되어있는지 확인해봐야합니다.

기본적으로 xcodebuild는 .xcodeproj파일을 빌드를 해주는데 현재 프로젝트가 .xcworkspace라면 제대로 빌드를 못해줍니다.

$ xcodebuild build -workspace workspace_name.xcworkspace -scheme scheme_name 

서두에 말했던것 처럼 위 명령어를 통해 xcodebuild가 잘 되는지 확인하고 jazzy의 build 옵션에 추가해줘야합니다.

$ jazzy -h
Usage: jazzy

Options
        --config PATH                Configuration file (.yaml or .json)
                                     Default: .jazzy.yaml in source directory or ancestor
    -b arg1,arg2,…argN,              Arguments to forward to xcodebuild, swift build, or sourcekitten.
        --build-tool-arguments
    -x arg1,arg2,…argN,              Back-compatibility alias for build_tool_arguments.
        --xcodebuild-arguments

jazzy의 -x 옵션값으로 위 build값을 추가해줍니다.

$ jazzy --clean -x -workspace,workspace_name.xcworkspace,-scheme,scheme_name --min-acl private