github pages에 DocC 정적 호스팅하기

커맨드라인을 활용해 정적 호스팅용 doccarchive export 후 github pages에 호스팅하는 과정을 설명하는 글입니다.

docc에 대한 이해가 있다는 전제하에 작성되었습니다. 이해가 부족하다면 애플 개발자 문서의 docc 관련 문서를 확인하시면 많은 도움이 될 것 같습니다. (번역 문서)

첫 번째 export 시도

swift-docc와 swift-docc-render를 모두 클론하여 xcodebuild 명령어 도움없이 docc 명령어만으로 정적 호스팅용 doccarchive를 export하는 방법입니다. 먼저, swift-docc-render을 npm install & npm run build 완료해 생성된 dist 디렉토리를 다음 명령어를 실행해 docc가 문서 카탈로그를 doccarchive로 변환할 때 참조할 디렉토리로 설정합니다.

export DOCC_HTML_DIR="dist location"

설정을 완료하고, 클론한 swift-docc 디렉토리로 이동하여 다음 명령어를 실행해 문서 카탈로그를 doccarchive로 변환을 시도합니다.

swift run docc convert framework.docc --fallback-display-name framework --fallback-bundle-identifier com.daeun28.framework --output-path ../framework.doccarchive --transform-for-static-hosting --hosting-base-path /base-path

그러나 현재(2022.01.18) 최신 상태의 swift-docc-render의 dist 디렉토리에는 data 디렉토리가 존재하지 않아 docc가 렌더링 시 각 문서별 실제 데이터를 가진 json을 생성하지 못합니다. 이에 따라 각 문서별 index.html이 생성되어도 데이터를 참조할 json 파일이 존재하지 않기 때문에 이 방법을 사용할 수 없었습니다.

두 번째 export 시도

swift-docc를 클론하고 xcodebuild 명령어를 사용해 문서 카탈로그를 doccarchive로 변환 후, docc 명령어를 사용해 정적 호스팅용 doccarchive를 export하는 방법입니다. 먼저, 다음 명령어를 실행해 문서 카탈로그를 doccarchive로 변환합니다.

xcodebuild docbuild -scheme framework

생성된 doccarchive를 찾기 위해 다음 명령어를 실행합니다.

find ~/Library/Developer/Xcode/DerivedData -type d -name '*.doccarchive'

명령어를 통해 찾은 doccarchive 위치를 다음 명령어 또는 Finder를 사용해 원하는 경로에 복사합니다.

cp -R ~/Library/Developer/Xcode/DerivedData/Project-aorfwyxbszouaxgduzhhcsuvdgdl/Build/Products/Debug/framework.doccarchive ~/Downloads

그리고 클론한 swift-docc 디렉토리로 이동하여 다음 명령어를 실행해 doccarchive를 정적 호스팅용으로 변환합니다.

• trasnform-static-hosting: doccarchive를 정적 호스팅용으로 변환하는 옵션
• ../framework.doccarchive: 변환할 doccarchive 경로
• --output-path ../docs: 변환 결과가 저장될 경로. 호스팅하기 위해 패키지 형태(.doccarchive)가 아닌 디렉토리에 하위에 결과가 생성되도록 지정
• --hosting-base-path base-path: 호스팅 시 필요한 base-path를 지정할 수 있는 옵션

자세한 내용은 관련 swift-docc pr을 참고해주세요.

swift run docc process-archive transform-for-static-hosting ../framework.doccarchive --output-path ../docs --hosting-base-path base-path 

Github pages에 정적 호스팅

이번 시리즈에서는 github actions를 사용하지 않고 위 단계에서 수동으로 export한 결과를 활용합니다. 먼저, 호스팅하려는 레포지토리에 github pages 설정을 합니다. 사진에서는 main 브랜치의 /docs 폴더 하위에 파일을 렌더링하도록 설정했습니다.

그리고 swift run docc process-archive transform-for-static-hosting 명령어를 사용할 때 --output-path를 렌더링되도록 설정한 폴더(/docs)로 지정하여 해당 폴더 하위에 렌더링 가능한 파일들이 바로 포함되도록 합니다. doccarchive 변환이 완료되면 결과를 commit, push합니다. 마지막으로 github pages가 active되면, 레포지토리의 github pages url/documentation/framework 경로를 통해 프레임워크의 문서에 접근할 수 있습니다.(예를 들어 https://daeun28.github.io/docc-static-hosting-test/documentation/xcode_k)

최종 결과물은 링크의 레포지토리에서 확인하실 수 있습니다. 혹시 첫 번째 export 시도와 같이 docc 명령어만으로 정적 호스팅용 doccarchive export에 성공하셨다면 방법 공유 부탁드립니다!

Reference

https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572 https://github.com/apple/swift-docc https://github.com/apple/swift-docc-render