[WWDC-2021] Meet DocC documentation in Xcode

이 글은 WWDC-2021 영상을 정리하여 작성한 글입니다.

원본 영상은 링크를 참고하여 주세요.

Meet DocC documentation in Xcode

오늘 소개해드릴 영상의 주제는 DocC 입니다. DocC 는 무엇일까요 ?!

DocC는 Xcode 13에서 새롭게 추가된 Swift 프레임워크 및 패키지에 대한 문서를 직접 작성하고, 탐색할 수 있는 기능입니다.

Xcode 13에서는 코드 뿐만 아니라 문서를 위한 컴파일러가 함께 제공되며, Swift 프레임워크와 패키지를 위한 문서를 Xcode 안에서 만들고 볼 수 있습니다.

Xcode 13부터는 사용자가 작성하는 문서와 코드를 위한 컴파일러와 함께 제공되며 Swift 프레임워크와 패키지를 위한 문서를 Xcode 안에 만들고 볼 수 있습니다. 이는 기존의 Quick Help 에서 나타낼 수 있는 문서 환경이나 코드 완성 기능에서 볼 수 있는 설명, 기존의 개발자 문서보다 향상된 개발 문서에서 업그레이드 된 문서를 확인할 수 있는 기능 또한 제공합니다. 이렇게 문서화를 위한 작업은 단순히 프레임 워크 내부에 대한 설명 뿐만 아니라, 프레임워크에 대한 Article, 그리고 튜토리얼 까지 작성할 수 있습니다. 

DocC에 대한 자세한 예제 파일은 링크를 통해 볼 수 있습니다. 물론 Xcode 13 beta 버전이 설치되어 있어야 하지만, 확인해보시면 정말 놀라운 문서라고 생각이 듭니다.

Xcode 13에서  이러한 문서에 대한 빌드를 하는 방식은 여러가지가 있습니다.먼저 개별적인 빌드가 필요한 상황이면 Xcode 13에서 Product > Build Documentation을 실행시키는 방법 입니다.

또한, 문서에 대해 즉각적인 preview가 필요하다면, 컴파일할때마다 문서를 작성해주는 빌드 세팅을 설정해줄 수 있습니다.

이는 Target에서 Build Settings > Documentation Compiler - Options > Build Documentation during 'Build' 설정을 YES로 체크하면 됩니다.

또한 command-line이나 CI를 원한다면, 'xcodebuild' 명령어를 통해 문서를 빌드할 수 도 있습니다.

이제 간단하게  직접 문서를 작성해 보도록 하겠습니다. 

 

먼저 Xcode 13으로 새로운 프로젝트를 생성하여 위와 같이 Framework로 프로젝트를 생성하면, 아래와 같은 구조로 프로젝트가 생성됩니다. Sloth.docc라는 파일이 먼저 눈에 띄는데요.

Sloth.docc 내부에는 몇가지 파일들이 있지만, Sloth.md를 먼저 살펴보면 다음과 같이 되어 있습니다. 이는 Document 문서에서 가장 상단에 위치한 문서를 나타냅니다.

이 상태로 문서를 빌드 하면, Xcode 내부의 개발자 문서 창이 열리는데 여기서 Sloth 프레임워크가 생성됩니다. 

이렇게 생성된 프레임워크 문서를 md 파일을 수정하면, 다음과 같이 볼 수 있게 됩니다.

md 파일 뿐만 아니라, 소스코드 내부에도 기존에 문서화 작업에서 쓰였던 문법들을 사용하면 자세한 문서를 작성할 수 있습니다. 

이렇게 작성한 문서들을 파일로 Export 할 수 있는 방법 또한 제공합니다.