Jazzy) 마크다운 자동문서화

jazzy Github

 

jazzy는 프로젝트 내의 마크다운 주석을 개발문서로 만들어주는 커맨드라인 유틸리티입니다.

Swift와 Object-C 모두 지원합니다.

여기서는 Swift에 대해서만 다루겠습니다.

 

1. jazzy 설치

sudo gem install jazzy

 

2. 문서화하기 원하는 프로젝트의 폴더로 이동

 

3. 문서 생성

jazzy --min-acl internal

* --min-acl:  minimum access control list 최소접근 지정자의 약자인 듯합니다. internal 영역까지 문서를 생성하라는 의미입니다.

* 개인적인 에러상황이나 스택오버플로어를 참고한 결과, 빌드시 xocde에서 경고표시가 없어야 제대로 문서를 생성합니다.

 

문제 발생

새로 생성해서 바로 jazzy를 사용하면 문서가 작성됩니다.

그런데 cocoapod을 이용해서 라이브러리를 설치하면 xcodebuild가 실패하고, 문서가 생성되지 않습니다.

자체 문제라고 보기에는 다른 사람들이 사용한 jazzy를 이용한 프로젝트와 라이브러리들이 있습니다. 곰튀김님 유튜브에만 봐도 엄연히  xcworkspace를 생성해서 예제를 만든 것이 확인되었습니다.

해결 방법을 찾는 중입니다.

 

문제 해결

jazzy를 계속해서 실행해본 결과 xcodebuild가 제대로 실행되고 있지 못하고 있었습니다.

그 이유를 보니깐, cocoapod으로 설치된 라이브러리들이 설정된 루트에 없다는 것이었습니다. 그런데 xcode를 실행해서 빌드하면 제대로 빌드가 되었습니다. 이 문제를 계속 생각하다보니깐, 현재 폴더에서는 xcode를 실행하는 파일이 2가지가 있었습니다. xcodeproj와 xcworkspace입니다. cocoapod을 사용하지 않으면, xcodeproj가 빌드되고 설정된 라이브러리 루트들이 없으니깐 제대로 빌드되었을 것입니다. 하지만 라이브러리를 설치하여 xcworkspace가 생성되면, 라이브러리 루트들이 build paths에 설정되고, 그것이 xcodeproj에도 적용되기에 라이브러리가 적용되지 않은 xcodeproj는 xcodebuild오류가 난다고 생각하였습니다.

 

그렇다면 우선적으로 xcodebuild가 제대로 실행된다면 jazzy문서화도 제대로 될 것이라 생각하였습니다.

xcodebuild -workspace sample.wcworkspace -scheme sample

제대로 빌드되었고, 이제 jazzy에서 wcworkspace를 빌드시키면 될 것 같습니다.

 

jazzy에서는

jazzy -x -workspace,sample.xcworkspace,-scheme,sample

로 작성하여 wcworkspace를 빌드하였습니다.

이제서야 제대로 빌드되어 문서를 생성하였다.

 

그런데 아무것도 안보였기에 다시

jazzy \ 
> --clean \
> --xcodebuild-argument -workspace,"sample.xcworkspace",-scheme,"sample" \
> --min-acl internal

로 빌드하자, 제대로 모든 클래스와 함수들이 제대로 생성되었습니다.

샘플로 만들어 본 문서입니다.

 

전에 위 커맨드로 문서를 생성했었는데 새롭게 해보니 또 빌드가 되지 않았습니다. 문제점을 다시 찾아보겠습니다.

jazzy 문서를 만드는데 xcodebuild를 시킬 커맨드를 찾아보니

jazzy --build-tool-arguments -workspace,ios.xcworkspace,-scheme,iosapp

가 있었습니다. 돌려보니 문서화가 되었습니다.

 

기존 커맨드도 블로그 글 작성 당시 테스트해가며 작성했던 것이었습니다. jazzy 문서화를 안되어서 고생하다가 성공시켜서, 혹시나 글을 잘못 작성할까봐 하나하나 테스트해가며 작성했던 것으로 기억합니다. 생성된 문서도 그때 만든 문서를 붙인 것인데 다시 작성했을때 왜 안되나 찾아보겠습니다.

---

참고

까칠코더

Jazzy 사용법

 

https://stackoverflow.com/questions/65634426/swift-jazzy-failing-to-run-xcodebuild

Swift: Jazzy failing to run xcodebuild