[iOS] 코드 문서화 도와주는 Jazzy 도전기

 

 

회사에서 새프로젝트를 진행하면서 개발 외에도 문서화가 정말 중요한 것을 느꼈습니다.

물론 깃이나 위키로 정리하여 문서화할 수 있지만 코드 관련 문서화는 한계가..

 

그렇게 찾아보다가 Jazzy를 알게 되었고, 지금도 여러 방식으로 수정하며 이용하고 있습니다.

 

 

https://github.com/realm/jazzy

GitHub - realm/jazzy: Soulful docs for Swift & Objective-C

 

objective-c 뿐 만아니라, swift도 모두 문서화가 가능합니다.

 

기본적인 사용법부터 확인해봅시다!

 

 

 

---

 

 

1. Jazzy Install

 

[sudo] gem install jazzy

 

터미널에서 위의 명령어를 입력하여 jazzy를 설치합니다.

 

 

2. sourcekitten Install

 

brew install sourcekitten

 

swift나 objective-c로만 구성되어있다면 jazzy만 사용하면 되지만 둘이 섞인 프로젝트는 지원하지 않습니다. 하지만 sourcekitten를 설치하면 문서화가 가능합니다.

마찬가지로 위의 명령어를 터미널에 입력해 설치해줍니다.

 

 

 

3. script 작성

 

설치가 완료되었다면 한 번 스크립트를 작성해봅시다.

 

sourcekitten doc -- -workspace [프로젝트 이름].xcworkspace -scheme [프로젝트 스키마]
                 > project.json

sourcekitten doc --objc $(pwd)/[프로젝트]-Bridging-Header.h \
       -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \
       -I $(pwd) -fmodules > objectiveDoc.json

jazzy --clean --min-acl internal --sourcekitten-sourcefile project.json,objectiveDoc.json

 

첫번째 명령어는 .swift 파일들을 json파일로 생성해주는 sourcekitten 명령어입니다.

두번째 명령어는 objective-c의 *.h 헤더파일 경로를 지정하여 json파일로 생성해주는 명령어입니다.

마지막은 jazzy 명령어에서 json file들 바탕으로 문서화를 해주는 명령어입니다.

 

이러한 방법으로 간단하게 문서화를 시켜줄 수 있습니다.

 

 

 

3-1. Jazzy.yaml 수정을 통해 문서화 커스텀

 

바로 끝내도 되지만.. 자신이 원하는 형태로 커스텀도 가능합니다.

예로 class지만 함수명을 묶고 싶다! (viewcontroller 끼리 묶을래!) 이러한 경우 직접 묶을 수는 있습니다.

하지만 묶은 메서드 외에 다른 아이들은 아래와 같이 

Other이 추가된 카테고리로 합쳐지게 됩니다.

 

 

 

Other을 넣고 싶지 않다면.. 모든 메서드를 정의해줘도 괜찮습니다 ㅎ..

 

copyright: ''
theme: fullwidth

custom_categories:
  - name: ViewController
    children:
    - [메서드]
    - [메서드]
  - name: API
    children:
     - [메서드]
...

 

.jazzy.yaml을 vi나 vim 편집기를 이용하여 이러한 방식으로 수정을 하면 됩니다.

해당 명령어는 정말 많으니 jazzy 공식문서에서 하나씩 넣어가며 테스트해보시는걸 추천드립니다 ㅎ..

 

 

 

3-2. 이외에 다른 커스텀 작업

 

jazzy만으로 커스텀해도 부족한 부분이 있었습니다.

 

 

objective-c 파일들을 jazzy 문서화 할 경우, 전역으로 만든 헤더파일들이 뭉쳐지지않고 저런 형태로 흩어져서 카테고리에 들어가게 됩니다.

해당 내용으로 역시 수정가능한지 연락을 받았지만.. 이는 jazzy만으로는 불가능한 것이였고..

 

방법이 없을까해서 만들어진 json파일들을 쭉 해석해보면서 생각해낸 결론은?

어쩌피 스크립트로 실행시키는 것이기에 jazzy 명령어 이전에 json파일을 수정하면 되지 않을까? 란 아이디어가 떠오르게 되었습니다.

즉! python을 이용해 json 파일을 수정해보자였습니다.

python을 이용해보지 않았기에 2시간정도 명령어들 학습해보고 수정해보니 바로 고칠 수 있었습니다.

 

 

먼저 json은 이러한 형태로 구성되는데 전역변수들은 key.name이 [Type Definitions]로 묶여있는 것을 보고 해당 내용들을 모두 key.structure로 다시 묶는 코드를 작성했습니다.

 

 

import os
import json

// 파일 열기 및 json 디코딩
input_file = open ('[파일 이름].json')
json_array = json.load(input_file)

// 디코딩 후, 내부 배열로 들어가기
filePath = os.getcwd() + "/Bridging-Header.h"
path_array = json_array[0][filePath]

// 추가 structure 생성
bridge_array = {"key.kind": "sourcekitten.source.lang.objc.decl.class", "key.name": "Bridge-Header",
                "key.substructure": []}

// 생성한 structure 배열에 집어넣기
for item in path_array['key.substructure']:
    bridge_array['key.substructure'].append(item)

// 구성된 structure으로 다시 내부 배열 수정
edit_array = {"key.diagnostic_stage": "", "key.substructure": [bridge_array]}
json_array[0][filePath] = edit_array

// json 인코딩 후 수정
with open("[파일 이름].json", "w") as json_file:
    json.dump(json_array, json_file)

 

위와 같이 디코딩 후, Key.Structure 배열을 만들어 해당 값들을 append 후 다시 배열을 수정하였습니다.

 

이렇게 파이썬으로 작업 후 실행해본 결과!

 

 

묶을 수 있었습니다 ㅎ.. 이건 제 주관적으로 코딩한 것이므로.. 아마 더 좋은 방법이 있을겁니다...

 

이외에도 sed 명령어를 이용하여 원하는 문자열들을 수정할 수 있습니다.

 

 

 

---

 

 

이렇게 저는 python이랑 sed 구문 등등 여러 방식을 쉘 스크립트에 추가하여 자동으로 문서화시켰습니다.

 

해당 방식을 이용하니 확실히 협업할 때도 정말 편했고, 설명을 할 때도 쉽게 보여줄 수 있어서 여러 이점이 있었습니다.

 

그러니!!

 

항상 문서화 하고 자동화 합시다 ㅎ..