여러 개의 DocC를 정적 호스팅하는 github actions workflow 생성하기

레포지토리에 포함된 여러 프레임워크에 대한 docc를 github actions를 활용해 자동으로 github pages에 호스팅하는 과정을 설명하는 글입니다.

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

프로젝트 구성

프로젝트 구조

프로젝트 구조가 아래와 다르다면, 원하시는 구조에 맞게 스크립트를 수정하시면 됩니다 :)

• 모든 패키지를 포함하는 xcworkspace
• 일부 패키지를 그룹화하는 디렉토리
  • 패키지
    • 하나의 패키지는 하나의 docc를 가집니다.
• dist 디렉토리
  • docc를 정적 호스팅용으로 변환할 때 사용됩니다.
  • swift-docc-render 레포지토리를 클론한 후, npm install & npm run build 명령어를 실행하여 생성된 dist 디렉토리를 사용합니다.

브랜치 구조

• main: docc만 포함하는 브랜치
• hosting: docc에 대한 빌드 결과를 포함하여 호스팅하는데 사용되는 브랜치

github pages 설정

• Source 브랜치: hosting
• Source 디렉토리: /docs
• 도메인: https://add-kr.github.io/
  • (organization or username).github.io 라는 이름으로 레포지토리를 생성하면, hosting-base-path에 레포지토리 이름을 포함하지 않아도 됩니다.

정적 호스팅용 doccarchive를 생성하는 스크립트 구현

스크립트의 목적은 /docs 디렉토리 하위에 각 패키지별로 정적 호스팅 가능한 docc 빌드 결과물이 export되는 것이기 때문에, 포함되어야 하는 작업은 다음과 같습니다.

1. 환경 세팅
2. workspace에 포함된 scheme list 찾기
3. 찾은 scheme과 xcodebuild 명령어를 활용해 docc 빌드
4. docc 빌드 결과물을 정적 호스팅용으로 변환하여 /docs 디렉토리 하위에 복사

bash shell script를 처음 작성하기에 개선 가능한 부분이 많을 것 같습니다. 제안은 언제든 댓글로 남겨주세요 :pray:

#!/usr/bin/bash

#1
brew outdated jq || brew install jq
sudo xcode-select -switch /Applications/Xcode.app
git clone https://github.com/apple/swift-docc.git

#2
schemeJSON=`xcodebuild -list -json`
schemes=`echo ${schemeJSON} | jq '.workspace.schemes'`

#3
for scheme in ${schemes}
do
    if [ ${scheme} != "[" ] && [ ${scheme} != "]" ] 
    then
        scheme=`echo ${scheme} | tr -d "\"" `
        scheme=`echo ${scheme} | tr -d "," `
        xcodebuild docbuild -scheme ${scheme}
    fi
done

#4
paths=`find ~/Library/Developer/Xcode/DerivedData -type d -name '*.doccarchive'`
export DOCC_HTML_DIR="dist"

cd swift-docc
swift build
for path in ${paths}
do 
    name=`echo ${path##*/}`
    name=`echo ${name%.doccarchive}`
    mkdir -p ../docs/${name}
    # 호스팅을 위해 패키지 이름을 가진 디렉토리 하위에 패키징된 doccarchive가 아닌 패키징되지 않은 상태로 export합니다.
    swift run docc process-archive transform-for-static-hosting ${path} --output-path ../docs/${name} --hosting-base-path ${name}
done

github actions workflow 작성

앞서 설명한 브랜치 구조에서는 docc 작업이 완료되면 main 브랜치에 push되지만, 실제 호스팅되는 hosting 브랜치는 업데이트되지 않습니다. 이에 따라 main 브랜치의 변경사항을 hosting 브랜치에 반영하고 최신 docc를 빌드하기 위해서 github actions의 workflow를 생성합니다.

docc와 관련없는 변경사항이나, 작은 변경사항이 있을 때에도 workflow가 실행되는 비효율이 있어 개선 에정입니다. 아이디어가 있으시면 언제든지 공유해주세요 :)

name: CD

# main 브랜치에 push가 발생할 때마다 workflow가 실행됩니다. 
on:
  push:
    branches:
      - main
    
jobs:
  hosting:
    runs-on: macos-latest
    steps:
    # github에서 제공하는 action을 활용해 이 레포지토리의 모든 히스토리를 불러옵니다.
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
    # git 설정 후, hosting 브랜치로 checkout하고 main 브랜치의 변경사항을 병합합니다.
    - name: setup git
      run: |
        git config --global user.name 'DAEUN28'
        git config --global user.email 'acone1128@gmail.com'
        git config pull.rebase false
        git pull origin hosting
        git checkout -t origin/hosting
        git merge main
    # 앞서 구현한 스크립트 실행 전, 모든 권한을 부여합니다.
    - name: grant sudo permission
      run: chmod 777 hosting.sh
    # 앞서 구현한 스크립트를 실행하여 /docs 디렉토리의 하위 디렉토리에 호스팅할 docc 빌드 결과를 업데이트합니다.
    - name: update hosting files
      run: sh hosting.sh
    # github pages에 호스팅하기 위해 변경사항을 커밋 & 푸시합니다.
    - name: git commit & push
      run: |
        git add -A
        git commit -m "Updated: `date +'%Y-%m-%d %H:%M:%S'`"
        git push

위 내용을 모두 적용한 최종 결과물은 링크의 레포지토리에서 확인하실 수 있습니다. 혹시 잘못된 내용이 있다면 댓글로 가감없이 남겨주세요.