jazzy를 이용해서 swift/objective-C로 작성된 코드 개발 문서 작성

API 개발을 하다보면 작성한 API들을 어떻게 사용하는지 명세를 해주는 문서가 하나쯤은 있어야 한다.

하나하나 만들면 API function이 추가할때마다 계속 업데이트해줘야 하고.... 매우 귀찮은 일이다. 이를 support해주는 아주 좋은 툴을 소개해볼까 한다.

 

https://github.com/realm/jazzy

realm/jazzy

ObjectiveC로 이루어진 프로젝트, Swift로 만들어진 프로젝트, 뿐만 아니라 Swift+옵씨로 이루어진 프로젝트도 모두 지원해준다:-)

일단 github page에선 macOS에서 돌릴것을 권장한다.

 

단 문서에 설명을 덧붙이기 위해서는 markdown type으로 주석이 모두 달려있어야 한다.

안그러면 아웃풋 문서에는 undocumented 로 출력된다.

즉, 소스코드에 markdown 형태로 주석만 잘 달아놓으면 jazzy가 이쁘게 문서화해준다.

 

1. Install jazzy

터미널에 아래와 같은 명령어를 입력해서 jazzy를 설치한다.

sudo gem install jazzy

 

2. Install sourcekitten

swift나 옵씨로만 구성된 프로젝트를 jazzy로 문서화 시키려면 jazzy만 있으면 되는듯하다. 원래 구버전에서는 둘 중 하나의 언어만 지원을 했다고 한다.

이번에 새로 나온 버전에서는 스위프트와 옵씨가 섞인 프로젝트를 하나로 문서화 할 수 있다. 이번 포스팅에서는 두가지 언어가 섞인걸 써야하니까 sourcekitten도 설치한다! 옵씨와 스위프트로 된 클래스들을 json file 로 아웃풋을 만들어주는 프로그램인듯..

 

https://github.com/jpsim/SourceKitten

jpsim/SourceKitten

홈브루로 아래와 같이 소스키튼을 설치해준다.

brew install sourcekitten

 

3. script

그리고나서 스크립트를 작성해주어야 한다.

# Generate Swift SourceKitten Output
sourcekitten doc -- -workspace ../WorkSpaceName.xcworkspace -scheme SchemeName > swiftDoc.json

# Generate Objective-C SourceKitten Output
sourcekitten doc --objc ObjectiveCHeaderFilePath \
      -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \
      -I $(pwd) -fmodules > objcDoc.json

# Generate jazzy
jazzy \
  --config .jazzy.json --disable-search \
  --sourcekitten-sourcefile swiftDoc.json,objcDoc.json \

 

첫번째줄은 *.swift 파일들의 json file을 생성해주는 sourcekitten 명령어이다. 그래서 swift파일이 존재하는 워크스페이스의 경로 및 이름과 스키마의 이름을 입력 후 swiftDoc.json file로 output을 내준다.

 

두번째줄은 *.h 옵씨 헤더파일 경로 지정 후 objcDoc.json 파일을 생성해준다.

 

마지막으로 jazzy 명령어에서 .jazzy.json file을 바탕으로 configuration을 구성하고, 출력한 이 두개의 파일을 결합해서 output path로 파일을 생성해준다.

 

 

https://realm.io/docs/swift/latest/api/

RealmSwift Reference

내가 만든건 아니지만, 이런 느낌으로 문서가 생긴다. :-)