안녕하세요! 올리브영🫒 iOS앱 개발자📱 럭셔Lee 입니다🙇♂️
이번 포스팅에서는 Apple에서 제공하는 문서화 도구, DocC에 대해서 이야기해보고자 합니다.
🤔 일단 DocC가 뭔가요?
DocC는 Xcode13부터 지원하는 Apple의 공식 문서화 도구입니다. Swift 또는 Objective-C 코드에 작성한 주석을 기반으로 문서를 생성할 수 있고, 별도의 Markdown 파일을 등록 가능한 도구입니다. DocC 문서 컴파일러는 주석이나 Markdown 기반 텍스트를 Swift 및 Objective-C 프로젝트를 위한 문서로 변환하고 Xcode 문서 창에 바로 표시합니다. 웹사이트에서도 DocC로 구성한 문서를 호스팅할 수 있습니다.
🫒 올리브영이 DocC를 도입하게 된 계기
올리브영에서는 타직군 동료들끼리 서로서로 가이드해줘야 하는 경우가 많고, 그 과정에서 문서를 사용합니다. 앱에서 관리하는 문서는 웹과 앱간의 인터페이스 가이드, 그리고 앱 로컬 빌드 가이드가 있습니다.
DocC를 도입하기 전, 올리브영 iOS 개발자들은 '컨플루언스'라는 도구를 활용하여 문서를 작성하고 있었습니다. 다시 말해 코드와 문서는 별도로 존재했고, 코드 작성 후 문서를 별도로 업데이트해야 했습니다. 하지만 개발에 집중하다 보니 문서 업데이트를 놓치는 경우가 자주 있었죠. 한번 뒤처지기 시작한 문서는 내용이 점점 빈약해졌고, 코드와 문서의 차이가 걷잡을 수 없을 정도로 벌어지기 시작했습니다. 이러한 문제를 해결하기 위해 고민하다가 발견한 도구가 DocC입니다.
DocC를 도입한 가장 큰 이유는 문서 업데이트를 강제할 수 있다는 점입니다. 예를 들어, JavaScript Interface를 추가하는 상황이라면 DocC 문서까지 만들어야 코드 리뷰를 통과하는 프로세스를 만들었습니다. DocC를 활용한 프로세스를 도입하니 문서가 코드에 비해 뒤처지지 않는 것은 물론이고 문서의 질도 좋아졌어요!👏🏻👏🏻👏🏻 인터페이스가 직관적이라 문서 확인이 수월한 것도 장점입니다.
심지어, DocC는 Xcode에 기본 내장되어 있어 별도의 설정 없이 바로 사용 가능합니다. 코드에 작성된 타입, 메서드, 파라미터 주석 등을 기반으로 자동 구조화한 문서를 생성해준다는 장점이 있습니다. 이런 장점은 공수가 덜 들어간다는 또다른 장점으로 이어집니다. 웹에 배포 가능한 환경 덕에 웹 브라우저를 통해 누구나 인터페이스를 확인할 수 있기도 합니다. 앱 개발자 이외에, 다른 영역의 개발자들도 인터페이스를 확인해야하는 경우가 있는데 이럴 때 소통 비용이 낮아지는 셈입니다. 꼬리에 꼬리를 무는 장점이죠?
🤔 DocC를 쓰면 뭐가 좋나요?
1. 문서 자동화로 시간 절약
개발을 하다보면 생각보다 문서 작성에 많은 시간을 소요하게 됩니다. 하지만 DocC를 사용한다면 주석(///)과 마크다운만으로 간단히 API 문서 생성하기 때문에 문서 작성에 드는 시간을 단축할 수 있어요. 또한 문서를 일일이 작성할 필요 없이 일관된 포맷 유지가 가능한 것도 큰 장점입니다. 한번 만들어 놓으면 코드 변경시 문서가 자동 업데이트 되기 때문에, 유지보수 측면에서도 상당한 이점이 있습니다.
/// 카메라로 인식한 물체가 어떤 물체인지에 대한 결과 값을 계산하는 함수 입니다.
func calculateAccuracy(results: [VNClassificationObservation]) {
guard
let top1Result = results.first
else {
showFailResult()
return
}
}
2. 검색 기능 및 직관적 인터페이스 제공
개발 중에 API를 통해 서버로부터 데이터를 가져와야 하는 경우가 종종 있습니다. 이 때 API가 제공하는 데이터와 데이터 타입을 확인하기 위해 관련 문서를 찾아야 하는데, 정리되지 않은 문서라면 이따금씩 불편함을 겪은 적이 있을 거에요. DocC를 도입하면 Xcode에서 한눈에 API 문서를 확인할 수 있습니다. 검색 기능이 포함되어 있어 원하는 정보를 빠르게 찾을 수 있죠. 단축키 Cmd + Shift + F를 활용해서 문서를 즉시 검색할 수도 있습니다.
3. 마크다운 기반 튜토리얼 및 다양한 포맷의 문서 작성 가능
DocC는 주석으로 작성 가능하고, 마크다운(.md)을 활용한 추가 문서 형태로도 작성할 수 있습니다. API 문서뿐만 아니라 개념 설명, 사용 예제, 튜토리얼 제작이 가능하기 때문에 다양한 용도로 활용할 수 있습니다.
# ``ImageClassification_CNN_iOS/LabelPicker``
@Metadata {
@DocumentationExtension(mergeBehavior: override)
@Available("AppVersion", introduced: "3.9.1")
}
비교하고자 하는 객체의 이름을 선택하는 PickerView입니다.
## 사용법
```swift
let labelPicker = LabelPicker()
## 파라미터
| params | type | description | required | encoding |
|:---:|:---:|:---:|:---:|:---:|
-| - | - | - | -
4. 강력한 협업 도구로 사용 가능
팀 협업 시 새로운 팀원이 DocC를 통해 프로젝트의 구조와 흐름을 빠르게 이해할 수 있어 코드 이해도가 향상됩니다. 또한 오픈소스 프로젝트에서는 API 문서를 명확하게 제공할 수 있어 외부 개발자들이 쉽게 활용할 수 있습니다. 사용자는 직관적인 문서를 통해 API를 효율적으로 사용할 수 있으며, 문서는 HTML 형태로 생성되기 때문에 GitHub Pages나 내부 서버를 통해 손쉽게 배포할 수 있습니다.
5. 코드와 문서 동기화
문서는 코드로부터 자동으로 생성되기 때문에 코드가 변경될 때마다 문서 역시 자동으로 업데이트됩니다. 이를 통해 문서와 코드 간의 불일치를 방지할 수 있으며, 결과적으로 문서를 따로 수정할 필요가 줄어서 문서 유지보수에 드는 비용을 크게 절감할 수 있습니다.
🤔 그렇다면 DocC로 문서를 어떻게 만들어요?
1단계: DocC 파일 생성하기
- File > New > File from Template을 클릭합니다.
- Documentation Catalog를 선택합니다.
- 이름과 Target을 설정한 후 Create 버튼을 클릭합니다.
2단계: DocC에 적용한 Contents 만들기
일반 함수 관련 Contents 만들기
- File > New > File from Template을 클릭합니다.
- Markdown File을 선택합니다.
- 일반 함수와 관련된 정보를 작성합니다.
-
#, ##: 대제목, 소제목을 가리킵니다.
-
@Metadata: 문서를 구성하는 데 필요한 메타 데이터를 선언합니다.@DocumentationExtension(mergeBehavior: override): docc 형식으로 표기하기 위해 필수적으로 선언하는 항목입니다.@Available("AppVersion", introduced: "v3.9.1"): 두 스트링 값이 합쳐져 라벨을 형성합니다.
-
*: 목록 형태로 나열하는 정보입니다.
-
표
- | param1 | param2 | param3 | .... |
- 파라미터를 표 형태로 기입합니다. 마크다운 문법을 사용해 가운데 정렬(|:-:|)합니다. 입력을 원하지 않는 컬럼도 빈 값으로 작성해야 합니다.
-
코드 작성
- ```{ programming language }
내용작성 private var olive: String ...- 스니펫 영역을 지정한 후 해당 코드의 언어를 언급합니다.
-
Tutorial 함수 관련 Contents 만들기
- File > New > File from Template을 클릭합니다.
- Tutorial Table of Contents File을 선택합니다.
- Tutorial Table과 관련된 정보를 작성합니다.
@Tutorials(name: ""): 제목을 입력합니다.@Intro(title: ""): 부제를 입력합니다.@Image(source: "", alt: ""): 이미지와 대체 텍스트를 입력합니다@TutorialReference(tutorial: "doc:"): 값의 맨앞에 doc:을 입력해 tutorial 파일을 읽어옵니다.
@Tutorials(name: "ImageClassfication-CNN-iOS") {
@Intro(title: "CNN모델 성능 측정기") {
iOS 디바이스 환경에서 CNN모델의 성능을 측정합니다.
@Image(source: "Intro.png", alt: "Intro")
}
@Chapter(name: "모델 변경 방법") {
@Image(source: "default.png", alt: "default")
@TutorialReference(tutorial: "doc:step-1")
}
}- Tutorial File을 선택합니다.
- Tutorial 파일과 관련된 정보를 작성합니다.
@Tutorial(time: ""): 해당 과정을 진행하는데 걸릴 예상 시간입니다.@Section(title: ""): 섹션 제목입니다.@Steps {}: 섹션을 수행하기 위해 거치는 단계입니다.@Step {}: 각 단계를 구체적으로 정의합니다.
@Tutorial(time: 10) {
@Intro(title: "모델을 변경하는 방법") {
iOS 앱 빌드를 위해 필요한 인증서를 설치하는 단계입니다.
}
@Section(title: "포함되어 있는 모델 확인") {
@ContentAndMedia {}
@Steps {
@Step {
mlmodel 폴더를 확인합니다.
}
@Step {
원하는 model이 있는지 확인합니다.
}
@Step {
원하는 model이 없으면 추가해줍니다.
}
}
}
@Section(title: "모델 변경") {
@ContentAndMedia {}
@Steps {
@Step {
전 단계에서 확인한 모델을 넣어줍니다.
@Image(source: "classificationModel.png", alt: "classificationModel")
}
}
}
}3단계: 빌드가 가능한 상태로 만들기
빌드할 수 있도록 트리 구조를 잡습니다.
- .docc File: 최상단 Docc 파일(Documentation.docc)입니다.
- .md Files: DocC를 구성하는 요소입니다.
- Resources Folder: 문서에 노출할 콘텐츠를 모아두는 폴더입니다.
- Tutorial Folder: 튜토리얼 관련 요소를 모아두는 폴더입니다.
- .tutorial Files: 튜토리얼을 구성하는 요소입니다.
4단계: 빌드하기
Product > Build Documentation을 클릭해 문서를 빌드합니다. 단축키 Ctrl + Cmd + Shift + D 로 빌드할 수도 있습니다.
📑 열심히 만든 DocC, 공유하려면 일련의 과정을 거쳐야 해요
1단계: DocC를 Package로 분리하기
- 새로운 프로젝트를 생성한 뒤, Package를 만듭니다.
- Empty를 선택합니다.
- Package 이름을 설정하고, 저장할 위치를 정해 Create을 클릭합니다.
- Package가 생성되었습니다.
- Pacakge.swift를 작성합니다.
- DocC를 구성하는 요소(markdown) 파일을 기술합니다.
- 빌드 단축키 Ctrl + Cmd + Shift + D를 실행해 문서를 빌드하고 정상 동작하는지 확인합니다.
2단계: 분리된 프로젝트에서 DocC를 웹페이지에 배포하기
- GitHub에 별도 레포지토리를 생성합니다.
- GitHub에 푸시할 데이터 구조를 잡습니다.
- Sources Folder: docc와 동일한 이름의 폴더를 생성합니다.
- docc File: 문서에 노출할 콘텐츠를 묶어주는 document package입니다.
- .md Files: 문서에 노출할 콘텐츠, 각 스킴 및 인터페이스 단위로 마크다운 파일을 작성합니다.
- Swift Files: 실제로 사용하는 스킴 및 인터페이스가 정의 되어 있는 파일입니다.
- docc File: 문서에 노출할 콘텐츠를 묶어주는 document package입니다.
- Package.swift: 기본이자 필수 영역으로, 패키지 관련 디스크립션을 설정합니다.
- build-docc.sh: docc를 읽어서, 웹에 호스팅하기 위한 환경을 만드는 빌드 스크립트입니다.
- Sources Folder: docc와 동일한 이름의 폴더를 생성합니다.
- build-docc.sh를 작성합니다.
##!/bin/sh
# docc 빌드
xcrun xcodebuild docbuild \
-scheme ImageClassificationSupport \ # 문서화할 스킴 이름
-destination 'generic/platform=iOS Simulator' \ # 빌드 대상 플랫폼
-derivedDataPath "$PWD/.derivedData" # 빌드 산출물 저장 경로
# doccarchive를 static-site로 변환
xcrun docc process-archive transform-for-static-hosting \
"$PWD/.derivedData/Build/Products/Debug-iphonesimulator/ImageClassificationSupport.doccarchive" \
--output-path ".docs" \
--hosting-base-path "ImageClassification-Support"-
빌드 스크립트 실행 및 쓰기(write) 권한을 부여합니다.
- 터미널에서 build-docc.sh가 존재하는 경로로 이동합니다.
- chmod +x build-docc.sh 명령어를 입력합니다.
./build-docc.sh명령어를 입력합니다.
-
GitHub Actions 스크립트를 생성합니다.
- Project Folder > .github > workflows 경로로 이동합니다.
- deploy-docc.yml 파일을 생성합니다.
- 파일 이름을 자유롭게 부여합니다.
- 확장자를 yml로 지정합니다.
- 다음과 같이 스크립트를 작성합니다.
name: deploy-docc on: push: branches: [main] # 타켓 브랜치 workflow_dispatch: permissions: pages: write id-token: write contents: read jobs: build: runs-on: macos-14 steps: - name: Checkout Repository uses: actions/checkout@v4 with: fetch-depth: 0 - name: Build Docs run: ./build-docc.sh - name: Setup for Github Pages id: pages uses: actions/configure-pages@v4 - name: Upload pages artifact uses: actions/upload-pages-artifact@v3 with: path: .docs deploy: runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }}
-
모든 데이터를 GitHub에 푸시합니다.
- Action 탭에서 deploy-docc를 선택합니다.
- Run workflow에서 작업한 브랜치를 선택합니다.
- Run workflow를 선택합니다.
- GitHub Actions에서 workflows가 제대로 동작하고 있는지 확인합니다.
- 완료되면 노란색 아이콘이 초록색으로 바뀝니다.
- 빌드가 완료 되면 Settings → Pages로 이동합니다. 배포가 완료된 주소(Base URL)를 확인합니다.
- Base URL에 /documentation/{ DocC PackageNamed }을 조합하여 브라우저에 입력합니다. DocC가 GitHub Pages에 잘 배포 되었는지 확인합니다.
3단계: 분리된 프로젝트를 SPM으로 가져오기
작업은 메인 프로젝트에서 진행합니다.
- File > Add Package Dependencies...를 클릭합니다.
- 오른쪽 상단에 새로운 레포지토리의 주소를 입력하고 Add Package를 클릭합니다.
- 종속되어야 하는 Project 선택 후 Add Package 선택합니다. 이후 프로젝트 빌드가 정상적으로 이루어지는지, DocC가 잘 동작하는지 확인합니다.
🫒 올리브영이 사용한 DocC는 어떤가요?
DocC 산출물
- 로컬 빌드 가이드
DocC 도입 전 로컬 빌드 1회 당 평균 15-20건이던 빌드 관련 문의가 도입 후 1-2건으로 약 90% 감소했습니다. Tutorial로 작성하였고, 단계마다 이미지를 더해 상세하게 안내하고 있습니다.
- JavaScript Interface 가이드
DocC 도입 전 주 평균 10-15건이던 인터페이스 관련 문의가 도입 후 1-2건으로 약 75% 감소했습니다. 웹과 앱이 통신하는 규격을 DocC로 정리하였습니다. Xcode 하나만으로 가이드를 확인할 수 있어서 직관적입니다.
- Github Pages로 배포
Xcode 외에도 인터넷 브라우저를 통해 DocC를 확인할 수 있도록 제공합니다.
DocC가 가져다주는 효과
앱 개발자가 아니어도 DocC로 생성한 문서를 볼 수 있다 보니 iOS 앱 빌드나 인터페이스 명세 정보에 대한 문의가 현저히 줄었어요. Xcode 내에서 인터페이스 검색이 가능한 덕에 앱 개발자들의 개발 속도는 점진적으로 향상되었습니다. 이 뿐만 아니에요. 웹페이지에서 확인할 수 있는, 접근성 측면도 향상되었습니다. DocC가 iOS 앱 개발자들에게 사랑받는 데는 다 이유가 있었어요.💕
이렇게 DocC를 작성하고 활용하는 방법에 대해서 간단하게 살펴보았습니다. 여러분도 DocC를 통해 문서 자동화에 성공하고, 성공적인 협업 도구로서 활용해 보시길 추천합니다! 더 자세한 내용은 DocC 공식 문서를 활용해보세요.
💍럭셔Lee💍 는 이만 물러가 보도록 하겠습니다~!
다음번에 만나요 안녕 👋🏻👋🏻
