[Swift DocC] 개념과 기능 (with WWDC)

뛰어난 개발자는 뭐라고 생각하시나요? 당연히 개발을 잘 하는 것입니다!

 

개발을 잘하는 것이, 잘하는 개발자의 조건이니까

 

그럼 개발을 잘 한다는 것은 무엇일까요?? 여러 가지 기준이 있겠지만 그 중 하나는 "쉬운 코드를 작성하는 것" 입니다. 저는 처음 이 말을 접했을 때는 이해가 안 됐습니다.

 

'쉬운 코드는 개발 초보들이 적는거 아닌가?'

 

하지만 개발을 하면 할 수록 조금씩 이해가 되기 시작했습니다. 몇 번의 프로젝트를 통해 앱을 만들면서 내 코드가 점점 복잡해지는 것을 느꼈습니다. 기능을 이렇게 구현하는 게 맞나하는 고민은 되지, 시간은 부족하지, 그렇게 코드는 팀에서 저만 이해할 수 있는 코드가 되었습니다. 만약 홈 화면 수정이 필요한 경우 팀원들은 직접 수정하지 않고 저에게 부탁하는 식이였습니다. 처음에 정했던 코드 리뷰 컨벤션이 있었지만, 프로젝트 후반부로 가서는 제가 작성하고 제가 머지하는 형식이 되었습니다.

 

뛰어난 개발자들의 코드를 보면 한 번에 이해할 수 있지만, 제가 작성한 코드의 이해를 돕기위해서는 문서가 필요합니다. 애플에서는 저같은 개발자를 위해 문서 작성을 도와줍니다. 바로 오늘 다룰 주제인 Swift DocC입니다.

 

 

 

개념

 

DocC는 Documentation Compiler의 준말

 

Swift DocC는 앱, 프레임워크, 패키지에 대한 API 문서와 튜토리얼(예제)를 생성합니다. Swift 공식문서 작성을 위해 애플이 지원해주는 툴입니다. DocC는 Markdown 기반 텍스트를 문서로 바꿔줍니다.

 

2021년에 정식 출시되서 매년 새로운 편의 기능들을 추가해주고 있습니다. 오픈 소스 프로젝트로 운영되고 있으니 관심 있으면 확인해보실 수 있습니다. swift-docc Github 바로가기

 

 

 

DocC로 만드는 문서는 크게 3가지 종류가 있습니다.

 

Reference

Reference는 공식 API 문서입니다. 클래스, 구조체, 메소드 등 애플 공식문서에서 확인하는 Swift 관련 코드가 다 여기에 속합니다.

 

https://developer.apple.com/documentation/swiftui/circle/

 

위 이미지에서 확인할 수 있듯이 코드에 대한 설명, 코드, 개요, 이니셜라이져, 메소드, 연관된 다른 문서들을 보여줍니다. 

 

 

Article

Article은 앱 프로젝트, 프레임워크에 대한 전체적인 설명을 하는 문서입니다. Github 레포지토리에 적는 Readme.md 파일과 같다고 볼 수 있습니다.

 

프로젝트 전체적인 개요, 설명, 이미지 등이 포함될 수 있겠네요. 아래는 애플에서 제공하는 DocC의 Article입니다.

 

https://developer.apple.com/documentation/docc/api-reference-syntax

 

 

Tutorial (튜토리얼)

튜토리얼은 앱, 프레임워크에 대한 코드와 이미지를 통해 사용법을 알려주는 문서입니다. 

 

애플에서 제공하는 SwiftUI 공식 튜토리얼처럼 앱 프로젝트, 프레임워크 사용법에 대한 튜토리얼도 만들 수 있습니다. Swift UI 튜토리얼 바로가기

 

SwiftUI - 공식 튜토리얼

 

 

 

동작 원리

WWDC 2021 - Meet DocC documentation in Xcode

 

Xcode가 Swift 컴파일러를 통해 프로젝트(앱, 프레임워크)를 빌드하고, 컴파일러에게 컴파일된 결과(Artifacts)와 공용 API 정보 저장을 요청합니다.

 

공용 API 정보가 DocC로 전달되고, 소스 코드 외부에서 작성된 DocC 카탈로그와 결합되어 최종 결과물(=DocC Archive)를 만듭니다.

 

쉽게 말해서 Xcode가 파일을 읽고 알아서 Swift 빌드하고 DocC 빌드해서 프로젝트와 문서를 만든다는 것입니다. 

 

 

Xcode를 사랑합시다

 

 

 

사용법은 간단합니다. Xcode 상단 메뉴 - Produc - Build Documentation을 해주면 됩니다. (Ctrl + + Shift + cmd + D)

 

 

 

빌드 설정을 통해 프로젝트를 빌드할 때마다 문서 빌드도 같이할 수 있습니다. 

 

Xcode - Project - Build Settings - "Documentation Compiler - Options" - Build Documentation During 'Build' 를 Yes로 설정하면 됩니다.

 

 

 

 

완성된 문서를 보는 것도 간단합니다. Xcode 상단 메뉴 - Window - Developer Documentation을 통해 확인가능합니다. (Shift + cmd + O)

 

프로젝트 문서

 

 

DocC 기능

DocC를 위해 지원하는 여러가지 기능있습니다.  WWDC2023에 추가된 기능으로 XCode preview가 있습니다.

 

WWDC 2023에서 추가된 Documentation Preview Editor

 

DocC가 처음 나왔을 때는 페이지를 직접 호스팅해줬어야 했지만 지금은 문서를 만들어 Github Repository에 Push하면 자동으로 호스팅이 됩니다. 

 

 

https://developer.apple.com/documentation/docc - DocC 공식 문서

 

웹에 호스팅하면 Apple 공식 문서와 같은 스타일을 가집니다. 

 

 

이 외에도 다양한 기능이 있습니다.

• 네비게이션 바에서 필터링
• 다양한 레이아웃 설정
• 커스텀 테마 설정

 

 

 

정리

WWDC 2023에서 DocC라는 기능을 처음 봤을 때 재밌고 편한 기능이라 생각됐습니다. 나온지 2년이 넘었는데 이제 알았다니... 아직 갈 길이 머네요 😅

 

DocC가 나온 2021년부터 WWDC 영상이 7개 정도 있는데 다 보고 정리하느라 시간이 조금 걸렸던 것 같습니다. (한국어 지원해줘.....) DocC 관련 WWDC 영상 링크는 아래 출처에서 확인할 수 있으니 관심 있으시면 보시는 것도 추천드립니다!

 

앞으로 예제 프로젝트를 통해 Documentation을 만들어 보며 DocC의 기능을 하나씩 확인해보겠습니다.

 

Swift DocC 개념 정리 끝 끝 끝 끝 끝

 

 

[Swift DocC] 문서 만들기 01 - Reference 만들기

 

[Swift DocC] Article(설명 글) 만들기

 

 

 

 

출처

DocC | Apple Developer Documentation

 

WWDC 2021

WWDC 2021 - Meet DocC documentation in Xcode

WWDC 2021 - Build interactive tutorials using DocC

WWDC 2021 - Elevate your DocC documentation in Xcode

WWDC 2021 - Host and automate your DocC documentation

 

WWDC 2022

WWDC 2022 - What's new in Swift-DocC

WWDC 2022 - Improve the discoverability of your Swift-DocC content

 

WWDC 2023

WWDC 2023 - Create rich documentation with Swift-DocC