클라우드 Mac에서 DocC 문서 품질 게이트 구축하기

팀에서 공개 API의 이름을 변경한 뒤에도 로컬 프로젝트는 계속 컴파일될 수 있지만, 문서에 남아 있는 이전 심볼 링크는 더 이상 유효하지 않습니다. 이런 문제는 대개 릴리스 직전에 문서를 사람이 직접 검토할 때야 발견됩니다. 더 안정적인 방법은 클라우드 Mac의 모든 병합 검사에서 DocC 빌드를 실행하는 것입니다. 해석할 수 없는 참조, 중복된 주제, 컴파일 경고를 즉시 실패로 처리하고 정적 사이트와 진단 로그도 함께 보관할 수 있습니다.

먼저 품질 게이트의 범위 정의하기

DocC 품질 게이트가 모든 문서 검사를 담당해서는 안 됩니다. DocC는 Swift 심볼, 문서 카탈로그, 주제 계층 구조, 내부 참조를 검증하는 데 가장 적합합니다. 외부 URL의 접근 가능 여부와 문체의 일관성은 별도 작업에서 검사하는 편이 좋습니다. 그렇지 않으면 일시적인 네트워크 시간 초과 한 번으로 코드 병합이 차단될 수 있습니다.

먼저 결과를 다음 세 가지 유형으로 구분하는 것이 좋습니다.

문서 품질 게이트의 목표는 모든 알림을 없애는 것이 아니라, 고정된 환경에서 동일한 입력에 항상 같은 결과를 내는 것입니다. 규칙은 개발 머신과 CI 노드에서 동일한 명령으로 재현할 수 있어야 합니다.

디렉터리도 단일 소스로 유지해야 합니다. 모듈 문서는 해당 target의 .docc 디렉터리에 두고, 여러 모듈에 걸친 가이드는 문서를 통합하는 target에 배치합니다. 같은 문서를 여러 catalog에 복사하지 마세요. 수정 후 일부 사본만 업데이트되기 쉽습니다.

Xcode와 빌드 입력 고정하기

원격 노드에서 가장 흔한 환경 차이는 Xcode 기본 경로에서 발생합니다. 작업을 시작할 때 버전을 먼저 출력하고 개발자 디렉터리를 명시적으로 검증하세요. 팀에서 여러 버전을 관리한다면 이전 대화형 세션의 선택에 의존하지 말고 CI 변수로 전체 경로를 전달할 수 있습니다.

set -euo pipefail

: "${DEVELOPER_DIR:?set DEVELOPER_DIR}"
: "${SCHEME:?set SCHEME}"

test -x "$DEVELOPER_DIR/usr/bin/xcodebuild"
xcodebuild -version
swift --version
git status --short

빌드 전에는 저장소 상태도 확인해야 합니다. CI는 깨끗한 체크아웃에서 시작해야 하며, 의존성 해석 파일은 반드시 버전 관리에 포함해야 합니다. 문서 생성에 필요한 리소스 파일도 개발자 디렉터리의 로컬 사본에 의존해서는 안 됩니다. 스크립트가 Markdown을 생성한다면 먼저 임시 디렉터리에 생성한 뒤 결과를 비교하고, 커밋되지 않은 차이가 발견되면 작업을 실패 처리하세요.

암묵적인 워크스페이스 상태 피하기

장기간 유지되는 DerivedData를 재사용하지 마세요. 오래된 심볼 그래프 때문에 삭제된 타입이 문서에 계속 나타나거나, 리소스 누락이 가려질 수 있습니다. 작업마다 독립된 디렉터리를 사용하고 종료 후에는 필요한 진단 정보와 DocC 산출물만 보관하세요.

재현 가능한 docbuild 실행하기

다음 스크립트는 작업마다 격리된 디렉터리를 만들고 DocC 경고를 오류로 승격하며 전체 로그를 보관합니다. generic/platform=iOS는 실행 중인 특정 시뮬레이터에 의존하지 않으므로, 심볼 그래프와 문서만 컴파일하면 되는 검사에 적합합니다.

set -euo pipefail

ROOT="$PWD/.build/docs"
DERIVED="$ROOT/DerivedData"
LOG="$ROOT/docc-build.log"

rm -rf "$ROOT"
mkdir -p "$ROOT"

set -o pipefail
xcodebuild docbuild \
  -scheme "$SCHEME" \
  -destination "generic/platform=iOS" \
  -derivedDataPath "$DERIVED" \
  OTHER_DOCC_FLAGS="--warnings-as-errors" \
  2>&1 | tee "$LOG"

ARCHIVE="$(find "$DERIVED/Build/Products" -name '*.doccarchive' -print -quit)"
test -n "$ARCHIVE"
printf '%s
' "$ARCHIVE" > "$ROOT/archive-path.txt"

scheme에 문서를 생성할 필요가 없는 target도 포함되어 있다면 로그에서 경고를 필터링하지 말고 프로젝트 설정에서 문서 컴파일 범위를 명확히 지정해야 합니다. 텍스트 필터링은 실제 회귀까지 함께 숨길 수 있습니다. --warnings-as-errors를 처음 활성화할 때는 비차단 작업에서 한 차례 실행해 기존 문제를 수정한 다음 병합 품질 게이트로 승격할 수 있습니다.

정적 사이트 내보내기 및 산출물 검증하기

.doccarchive는 후속 처리에 적합하지만, 검토자는 대개 바로 열 수 있는 정적 파일을 필요로 합니다. archive를 찾은 뒤 DocC에 포함된 변환 명령으로 사이트를 생성하세요.

set -euo pipefail

ARCHIVE="$(cat .build/docs/archive-path.txt)"
OUTPUT="$PWD/.build/docs/site"

xcrun docc process-archive transform-for-static-hosting \
  "$ARCHIVE" \
  --output-path "$OUTPUT" \
  --hosting-base-path docs

test -s "$OUTPUT/index.html"
find "$OUTPUT" -type f | sort > .build/docs/site-files.txt

--hosting-base-path는 최종 배포 하위 경로와 일치해야 합니다. 사이트가 실제로 루트 경로에 배포된다면 docs를 그대로 사용하지 마세요. 경로가 일치하지 않으면 로컬에서 홈페이지를 직접 열 때는 정상으로 보여도 배포 후 스크립트와 스타일 요청이 오류를 반환할 수 있습니다.

아카이브할 때는 최소한 빌드 로그, archive 경로, 정적 사이트, 파일 목록을 보관해야 합니다. 로그는 구체적인 진단 내용을 찾는 데 사용하고, 파일 목록은 비정상적인 대규모 삭제를 탐지하는 데 사용합니다. 정적 사이트에는 비교적 짧은 보존 기간을 설정할 수 있지만, 실패한 작업의 로그는 문제가 해결될 때까지 보관해야 합니다.

외부 링크 검사를 별도 작업으로 분리하기

외부 링크 검사는 생성된 HTML을 읽고, 접근이 허용된 https 주소만 제한된 동시성으로 검사해야 합니다. 시간 초과와 서버 측 요청 제한에는 제한적으로 재시도하고, 계속 실패할 때만 차단하세요. 임시 토큰, 쿼리 매개변수 또는 내부 주소가 포함된 링크는 공개 문서에 작성해서는 안 되며 검사 로그에도 남겨서는 안 됩니다.

일반적인 실패 처리 및 승인 체크리스트 만들기

“심볼은 존재하지만 DocC가 찾지 못하는” 문제에는 대개 세 가지 원인이 있습니다. 심볼이 현재 scheme에 속하지 않거나, 접근 수준이 문서화 범위에 포함되지 않거나, 링크에서 오래된 전체 시그니처를 사용한 경우입니다. 철자를 반복해서 바꾸며 추측하지 말고 먼저 target을 확인한 다음 생성 로그에 표시된 후보 심볼을 살펴보세요.

문서 링크가 유효하지 않다면 파일 이름, 제목에서 생성된 식별자, 카탈로그 내부의 상대 계층을 확인하세요. 리소스를 불러오지 못한다면 대소문자와 target membership을 점검해야 합니다. 클라우드 파일 시스템은 실제 경로를 정확히 따릅니다. 일부 로컬 환경에서 우연히 작동하는 잘못된 대소문자 표기는 유지해서는 안 됩니다.

최종 품질 게이트는 다음 질문에 답할 수 있어야 합니다.

• Xcode와 Swift 버전이 기록되었는가;
• 워크스페이스가 깨끗한 상태에서 시작되었는가;
• DocC 경고가 합의된 방식으로 처리되었는가;
• 예상한 archive를 찾았으며 해당 archive만 처리했는가;
• 정적 사이트의 진입점이 존재하는가;
• 빌드 로그와 파일 목록이 아카이브되었는가;
• 외부 링크 오류와 DocC 컴파일 오류가 분리되어 보고되는가.

이러한 검사를 모두 같은 스크립트로 실행하면 문서 변경도 코드 변경과 마찬가지로 재현 가능한 실패 상태를 갖게 됩니다. 유지관리자는 로그에서 참조 문제를 찾고 정적 산출물에서 구조를 검토할 수 있으며, Xcode를 업그레이드한 뒤에는 동작 차이도 명확하게 비교할 수 있습니다.

자주 묻는 질문