iOS) Documentation - DocC (1)

DocC를 이용한 문서화 후 github page 배포 테스트(Framework)

1. Framework 프로젝트 생성 후 코드 작성
2. 형식에 맞는 문서화를 위한 주석 작성
   • 형식은 Swift Documentation에 따름
3. Framework의 메인페이지를 작성하기 하기 위해 <project-name>.docc 내에 있는 <project-name>.md 파일 수정
4. Developer Documentation으로 문서화를 하기 위해 Product - Build Documentation
5. 빌드가 완료되면 Developer Documentation으로 들어가서 해당 프레임워크 문서 - export
6. doccarchive파일이 프로젝트 디렉토리에 생성되는데 이를 static page로 전환하기 위해 swift-docc, swift-docc-render 설치
7. clone한 swift-docc 디렉토리 내에서 명령어 입력(hosting base path는 base url이라고 생각하면 됨)
8. 해당 output을 github repository에 commit, push(gh-pages)
9. <username>.github.io/<repo-name>/documentation/<framework-name> 으로 접속 후 확인
    

$ swift run docc process-archive transform-for-static-hosting [.doccarchive path] --output-path [output path] --hosting-base-path [github repository name]

결과

docc 빌드 결과로 생성된 output

Github Page

• • <username>.github.io/<repo-name>로 들어가면 페이지에 빈화면 표시
  • framework-name은 대문자가 있었더라도 url에는 모두 소문자로 표기<username>.github.io/<repo-name>/documentation/<framework-name>로 들어가야만 볼 수 있음

---

 

비고

Xcode상에서 문서화한 항목을 토대로 .doccarchive를 만드는 방법

Product - Build Documentation

→ Developer Documentation → export

or

→ xcodebuild docbuild -scheme <scheme>

 

static page로 전환하기 위해 docc 명령어를 사용해야 하는데, 이 때 설치해야 하는 것들

swift-docc : git clone 후 swift build

swift-docc-render : git clone 후 → npm install → npm run build

 

swift run docc ... 명령어 실행시 DOCC_HTML_DIR 찾을 수 없다고 나올 때

→ swift-docc-render의 dist를 경로로 지정해주어야 함

export DOCC_HTML_DIR="[swift-docc-render build한 dist 디렉토리]"