DocFX를 이용한 Unity 패키지 문서 작성과 배포 자동화

개요

기존에는 Unity 패키지의 기본 구조를 만드는 도구로 Package Generator를 사용하고 있었습니다. 여기에 패키지 문서도 함께 제작하고 배포할 수 있도록 문서 생성 기능을 추가했습니다.

문서 제작에는 DocFX를 사용했습니다. Markdown으로 작성한 사용 가이드와 C# 코드 기반의 API 문서를 하나의 사이트로 구성하고, 패키지마다 필요한 문서 구조와 설정은 템플릿으로 제공했습니다.

핵심은 문서를 빠르게 작성할 수 있는 작업 흐름을 만드는 것이었습니다. 목차 생성과 링크 검사, 로컬 미리보기, 배포를 위한 빌드 과정을 자동화해 반복 작업을 줄였습니다. 이 글에서는 Package Generator에 이 흐름을 어떻게 연결했는지 정리합니다.

Package Generator
    → 문서 템플릿 생성
    → 사용 가이드 작성·API 대상 설정
    → 로컬 검사·빌드·미리보기
    → GitLab CI 연결을 통한 문서 배포

Unity 패키지 문서에 DocFX 사용하기

패키지를 사용하는 개발자에게는 설치와 초기화 방법을 설명하는 가이드와, 개별 API의 역할을 확인할 수 있는 문서가 모두 필요합니다. 이번 구성에서는 두 문서를 DocFX로 묶었습니다.

사용 가이드는 Markdown으로 작성하고, API 문서는 대상 C# 프로젝트와 코드 주석을 바탕으로 생성합니다. 작성자는 설치 순서와 사용 예제처럼 설명이 필요한 부분에 집중하고, API 목록은 코드에서 생성하는 방식입니다.

문서 소스와 빌드 설정은 패키지 저장소 안에서 함께 관리합니다. 코드 변경에 맞춰 가이드를 수정하고, 같은 저장소에서 문서 사이트까지 만들 수 있도록 구성했습니다.

Package Generator에서 문서 작업 시작하기

문서를 추가할 때마다 폴더와 설정을 처음부터 만들지 않도록, 기존 Package Generator에 문서 템플릿을 넣었습니다. Unity 에디터의 문서 탭에서 대상 패키지와 테마를 선택한 뒤 Generate Documents를 누르면 Documentation 폴더가 생성됩니다.

주요 구성은 다음과 같습니다. 도구 버전은 .NET local tool manifest에 고정하고, 실제 문서는 docfx 아래에서 관리합니다.

Documentation/
├── .config/dotnet-tools.json   도구 버전
├── GenerateDocWebsite.sh      macOS/Linux 실행 스크립트
├── GenerateDocWebsite.ps1     Windows 실행 스크립트
└── docfx/
    ├── docfx.json             API 대상과 사이트 빌드 설정
    ├── manual/                사용 가이드
    └── images/                문서 이미지

생성 과정에서는 Unity 프로젝트의 상대 경로와 패키지 표시 이름을 설정에 반영합니다. 선택한 테마도 함께 지정하므로, 새 문서마다 같은 기본 설정을 반복할 필요가 줄어듭니다.

다만 API를 추출할 .csproj 파일명까지 모두 결정해 주는 것은 아닙니다. 현재 템플릿에는 해당 파일명의 자리표시자가 남아 있으므로, 작성자는 docfx.json에서 문서화할 프로젝트를 확인하고 지정해야 합니다.

생성 결과인 api와 _site 폴더는 Git 관리에서 제외합니다. 문서 소스와 설정을 관리하고, API 문서와 HTML은 빌드할 때 다시 만드는 구조입니다.

문서 생성 과정을 한 번의 실행으로 묶기

초기에는 별도의 .NET 실행 프로젝트가 DocFX를 호출했습니다. 이후 이 역할을 실행 스크립트로 옮기고, 필요한 도구는 .NET local tool로 복원하도록 변경했습니다. 문서 생성을 위해 유지하던 실행 프로젝트 대신, 스크립트에 처리 순서를 모았습니다.

작성자는 Documentation 디렉터리에서 다음 명령을 실행합니다. 아래 예시는 macOS/Linux용 스크립트를 기준으로 설명합니다.

./GenerateDocWebsite.sh

스크립트는 다음 작업을 순서대로 수행합니다.

1. 도구 복원 — manifest에 지정된 DocFX와 링크 검사·목차 생성 도구를 준비합니다.
2. 이전 결과 정리 — 앞서 생성한 api와 _site를 제거합니다.
3. 링크 검사 — 문서의 링크와 첨부파일 참조를 검사합니다.
4. 목차 생성 — manual 폴더를 기준으로 목차를 생성하고 후처리합니다.
5. 사이트 빌드 — DocFX로 API 문서와 HTML 사이트를 생성합니다.

이전 결과를 먼저 정리하는 것은 링크 검사에 빌드 산출물이 섞이는 것을 막기 위해서입니다. 검사나 생성 단계가 실패하면 이후 단계로 진행하지 않으며, 오류가 난 작업을 확인할 수 있도록 메시지를 출력합니다.

목차를 자동으로 만들면 문서 파일을 추가할 때 메뉴를 별도로 수정하는 작업도 줄어듭니다. 메뉴 순서나 표시 이름을 조정해야 할 때는 .order와 .override 파일로 관리합니다.

수정한 내용을 바로 확인하기

문서를 작성하는 동안에는 결과를 자주 확인해야 합니다. 파일을 고칠 때마다 빌드 명령을 다시 실행하고 브라우저를 새로고침하는 과정을 줄이기 위해 --watch 옵션을 추가했습니다.

./GenerateDocWebsite.sh --watch

처음 실행하면 도구를 복원하고 전체 검사와 빌드를 수행한 뒤 로컬 서버를 시작합니다. 이후 nodemon이 문서와 이미지, 테마 파일 등의 변경을 감지하면 목차와 사이트를 다시 생성하고, browser-sync가 브라우저를 새로고침합니다.

최초 실행과 변경 후 재빌드의 범위는 다릅니다. 변경을 감지했을 때는 목차 생성과 DocFX 빌드만 수행하며, 매번 도구 복원이나 링크 검사를 반복하지는 않습니다.

로컬 서버는 8000번부터 사용 가능한 포트를 찾습니다. 다른 문서 사이트가 이미 실행 중이어도 해당 프로세스를 종료하지 않고 다음 포트를 사용하도록 했습니다.

생성한 문서를 배포 흐름에 연결하기

로컬에서 확인한 문서를 배포할 수 있도록 GitLab CI에도 문서 빌드·배포 흐름을 연결했습니다. 현재 .gitlab-ci.yml은 패키지 검사와 배포용 공용 템플릿에 더해 docfx-publish.yml을 포함합니다.

문서 생성 스크립트는 배포 주소를 첫 번째 인자로 받을 수 있습니다. 이 값을 이용해 index.md의 redirect_url을 해당 배포 경로의 사용 가이드 첫 페이지로 갱신합니다. 저장소마다 달라지는 문서 진입 경로를 스크립트에서 반영할 수 있도록 한 것입니다.

패키지 저장소에서는 공용 CI 템플릿을 연결하고, 문서 소스와 빌드 설정을 관리합니다. 공용 템플릿 내부의 실행 명령과 배포 조건은 별도 저장소에서 관리하므로, 이 글에서는 현재 저장소에서 확인할 수 있는 연결 구조까지만 다룹니다.

여러 패키지에서 같은 작업 흐름 유지하기

문서 템플릿을 복사해 제공하면, 이후 스크립트를 개선해도 이미 생성된 문서에는 예전 파일이 남습니다. 이를 보완하기 위해 Package Generator에 문서 스크립트 업데이트 기능도 추가했습니다.

자동 업데이트 확인이 켜져 있으면 Unity 시작 시 설치된 템플릿과 해당 저장소의 scriptVersion을 비교합니다. 새 버전이 있을 때 사용자가 업데이트를 선택하면 셸 스크립트, PowerShell 스크립트, 도구 manifest를 함께 교체합니다. 자동 확인은 문서 옵션에서 끌 수 있습니다.

문서의 읽기 환경도 함께 개선했습니다. 생성 시 Classic과 Material 테마를 선택할 수 있도록 했고, 이후 Classic 테마에는 다크·라이트 모드도 추가했습니다.

이렇게 Package Generator의 역할을 문서 작업을 시작하고 유지하는 단계까지 확장했습니다. 작성자는 문서 내용을 수정하고 결과를 확인하며, 반복되는 목차 생성과 검사, 빌드는 도구가 수행합니다.

자동화가 문서의 설명까지 대신해 주지는 않습니다. 사용 순서가 이해하기 쉬운지, 예제가 실제 API와 맞는지는 작성자가 확인해야 합니다. 반복 작업을 줄여 확보한 시간을 이러한 내용 점검에 쓸 수 있도록 하는 것이 이번 기능의 목표입니다.