Swift-DocC의 새로운 기능

♪ 부드러운 힙합 반주 ♪ ♪ 안녕하세요, Franklin입니다 전 Swift-DocC 팀의 기술자인데 제 동료 Ethan과 함께 Xcode 14의 Swift DocC를 소개한다니 들뜨죠 더 나은 문서 작성에 유용한 새로운 도구가 가득하거든요 작년에 Xcode 13에서 소개한 Swift-DocC는 Swift 프레임워크를 개발자에게 소개하게 해 주죠 Swift-DocC로 포괄적인 콘텐츠를 작성합니다 개별적인 API 참조 문서부터 수준 높은 내용이 담긴 개념적인 글까지 이런 API를 함께 사용해 단계적인 튜토리얼로 끝까지 사용자가 작업을 파악하게 해 줍니다 올해 Xcode 14에서 Swift-DocC이 새롭고 흥미로운 워크플로를 공개했죠 프레임워크 기록뿐 아니라 앱 프로젝트까지 지원하니 기쁜 일입니다 팀원들과 쉽게 협력할 수 있게요 이젠 Swift-DocC로 Objective-C와 C API도 쓸 수 있어서 프로젝트 API를 다 같이 기술할 수 있죠 GitHub Pages 같은 고정적인 호스팅 환경에서 기본 제공 기능으로 웹사이트 콘텐츠 발행이 몰라보게 쉬워졌습니다 그리고 강력한 새로운 탐색 사이드바 덕분에 개발자들이 그 어느 때보다 쉽게 콘텐츠를 찾을 수 있게 됐어요 또한 Swift-DocC는 오픈 소스 프로젝트라 오픈 소스 커뮤니티에서 긴밀히 협조하며 이렇게 새로운 특징을 개발했습니다 이 세션에선 Swift DocC와 Xcode 14에서 공개하는 흥미로운 새 워크플로를 소개합니다 우선 소스 코드로 바로 프로젝트 API를 기록하는 방법부터 알아보겠습니다 그리고 콘텐츠를 웹사이트에 끊임없이 발행하는 방식을 살펴보죠 마지막으로 웹의 새로운 탐색 사이드바를 알아보겠습니다 그럼 문서 작성부터 시작해 보죠 좋은 문서는 소프트웨어 프로젝트에 필수적입니다 프로젝트가 진화하면 기능과 디자인을 기술하는 게 중요하죠 개발자가 기여할 때 확고한 참조점을 갖추게요 Xcode의 Swift DocC는 환상적인 문서 작성에 필요한 도구를 제공하죠 코드 개발에 쓰는 것과 같은 도구를 써서요 올해는 앱 프로젝트로 Swift-DocC를 확장하니 기대됩니다 그럼 바로 살펴보겠습니다 우리 팀이 작업하는 '슬로시'란 앱을 기록해 볼게요 Swift와 Objective-C 소스 파일이 다 담겨 있죠 아직 기록하지 않은 새로운 프로젝트라고 해도 Product 메뉴를 열어서 문서 작성을 선택하면 Xcode가 문서 창을 열어서 Swift-DocC가 API용으로 자동 생성하는 스텁이 나타납니다 기여자가 이 프로젝트를 둘러보는 데 유용한 페이지를 채우는 훌륭한 시작점을 제공하죠 그럼 단계적으로 이 콘텐츠를 우리 앱에 기여하는 풍성하고 완전한 가이드로 바꿔 보겠습니다 API가 각각 어떻게 작동하는지부터 배우는 게 좋죠, 그다음엔 문서 카탈로그로 수준 높은 콘텐츠를 제공하는 법도요 그럼 '슬로스뷰'라는 뷰의 설명으로 시작하죠 Swift-DocC에 이 문서가 나타나게끔 사선 세 개 다음에 코맨트를 시작하세요 그리고 뷰의 간결한 개요를 추가하고요 문서 작성 페이지에서 텍스트로 번역되면 뷰 이름 바로 밑에 확실하게 나타납니다 그리고 추가 단락에 세부 사항을 덧붙이세요 이 내용은 페이지의 Overview 부분에 나오죠 그리고 Swift-DocC 링크 구문으로 API 참조 사항을 활성 링크로 바꾸면 신속히 Pages로 넘어가 더 배울 수 있어요 DocC는 빌드 중에 이런 링크도 인증해서 유효 기간이 지났다면 경고가 뜹니다 마지막으로 이 뷰를 어떻게 쓰는지 예시를 제공하려면 마크다운 코드 블록 문법으로 코드 목록을 추가하세요 이젠 이 뷰의 사용법을 개발자가 한눈에 알 수 있습니다 몇 단계만으로 제 뷰의 기록이 이 프로젝트 기여자에게 훨씬 더 유용해졌습니다 다음 차례로 이니셜라이저를 기록해 보죠 역시 개요를 쓰는 것부터 시작합니다 이니셜라이저와 메서드는 매개 변수마다 개별적으로 기술하는 게 좋죠 이러려면 매개 변수 리스트 항목을 추가하고 어떤 매개 변수인지 간략하게 설명합니다 이 내용이 어떻게 매개 변수 구역에 나뉘어 나타나는지 보세요 이젠 이 프로젝트를 정의하는 Objective-C API를 살펴보죠 Xcode 14에서 새롭게 기대되는 점은 Swift-DocC의 포괄적인 도구로 Objective-C 코드를 쓴다는 겁니다 여러분이 알고 사랑하는 친숙한 마크다운 문법과 Xcode 소스 편집기의 업데이트 지원으로 이젠 여러분의 프로젝트 API를 다 같이 기술하고 구성할 수 있습니다 Swift와 Objective-C에서 불러온 코드는 실용적인 언어 토글로 페이지를 코딩한 언어로 둘러볼 수 있습니다 세부 사항은 아래쪽에 링크된 개발자 문서에서 확인하세요 이젠 우리 슬로시 프로젝트에 적용해 봅니다 SLOSound 클래스와 이니셜라이저를 기술해 보죠 Swift와 Objective-C 코드에 다 쓰는 클래스니 알아두세요 Xcode에 나타나는 언어 토글로 여러분이 쓰는 언어로 내용을 살펴볼 수 있죠 여러분이 Swift 코드에 쓰는 마크다운 문법으로 클래스와 이니셜라이저를 기술해 봅니다 좋아요 훨씬 더 나아 보이네요 제가 Overview에 개요를 추가하고 이니셜라이저엔 매개 변수 구역을 더했죠 개별 API 설명은 이렇게 마무리할게요 소스 코드에서 문서 코맨트를 몇 마디 쓰면 제 프로젝트에 기여하는 개발자가 API 사용법을 더 잘 파악할 수 있습니다 이젠 앱의 탁월한 톱 레벨 페이지 만들기에 초점을 맞추죠 기여자가 보게 될 첫 번째 페이지니 어떤 앱이고 어떻게 기여할 수 있나 제가 탁월하게 소개하고 싶습니다 톱 레벨 페이지 설정은 문서 카탈로그 추가로 시작됩니다 이렇게 하려면 프로젝트 소스 폴더에서 우클릭해 '새 파일'을 선택하세요 그다음엔 문서 카탈로그를 선택하고요 문서 카탈로그는 소스 코드 문서를 보완하며 추가적인 마크다운 파일과 매체가 담겨 있죠 Xcode는 앱의 톱 레벨 페이지용 파일을 자동적으로 추가합니다 이 앱의 기능 개요를 써서 채워 보겠습니다 소스 코드에 문서 코맨트에 쓰는 것과 같은 구문으로 요약한 내용과 개요를 추가하고 이미지 같은 풍성한 콘텐츠까지 담았습니다 좋아요, 훨씬 더 마음이 끌리네요 이젠 기여자가 어떤 앱인지 한눈에 알 수 있습니다 이제 됐습니다 제 앱의 문서를 몰라보게 개선시키고 제 프로젝트 기여자에게 훌륭한 참조점을 제공했죠 톱 레벨 페이지의 프로젝트 개요를 보고 각 페이지로 넘어가 API 각각의 상세한 정보를 얻을 수 있습니다 문서를 어떻게 쓰고 만드는지 봤으니 웹사이트에 발행할 차례입니다 기여자들이 쉽게 훑어볼 수 있게요 Ethan에게 넘길게요 고마워요, Franklin 우린 슬로시 앱을 모듈식으로 개발했습니다 더 일반적으로 유용한 '슬로스크리에이터'란 Swift 패키지와 함께요 슬로스 관련 앱을 만드는 개발자도 쓸 수 있게 더 많은 분들께 슬로스크리에이터를 발행하는 게 좋겠죠 그런 노력의 일환으로 슬로스크리에이터의 문서를 웹에서 쉽게 공유하길 바라니까 새롭게 간소화환 Swift-DocC의 발행 워크플로를 살펴보겠습니다 Xcode에서 문서를 만들 땐 Swift-DocC가 여러분의 문서를 포함하는 번들을 제공합니다 이 번들을 DocC 보관소라고 하며 여러분의 휴대용 문서 기기입니다 Xcode의 문서 창에서 바로 발송해서 동료에게 보낼 수 있죠 이 보관소를 더블 클릭만 하면 이 문서를 열고 훑어볼 수 있습니다 DocC 보관소는 Xcode의 문서를 여는 휴대용 기기에 그치지 않아요 별도의 설치 없이 특색을 다 갖춘 웹사이트도 담겨 있죠 Xcode 14의 새로운 DocC 보관소는 대부분의 웹 서버와도 직접적으로 호환되니 그 어느 때보다 웹 문서 발행이 쉬워졌습니다 대개 설치한 DocC 보관소 콘텐츠를 여러분의 웹 서버 루트에 복사하기만 해도 여러분의 문서를 쓸 수 있습니다 이젠 GitHub Pages 같은 전용 서버 대부분과 호환된다는 의미도 있습니다 GitHub Pages는 대중적으로 많은 개발자가 GitHub 닷컴에 통합되는 문서를 관리하는 방식입니다 슬로스크리에이터의 소스 관리용으로 GitHub를 쓰니까 거기서 우리 문서도 발행하는 게 이치에 맞죠 GitHub pages를 쓰는 데 익숙하다면 알게 되실 텐데 표준 서버와 달리 URL의 루트 경로가 아닌 특정한 기본 경로에서 여러분의 웹사이트가 발행됩니다 이런 호스팅 시나리오에선 호환되는 DocC 보관소를 제공하게 추가적인 빌드 설정으로 여러분 웹사이트 기본 경로를 명시해야 해요 이 원리와 GitHub Page 같은 호스팅 시나리오에서 왜 이런 설정만 필요한지 완전히 이해하려면 여러분 도메인에서 관리되는 보관소 모습을 어떻게 예상할지 살펴봐야죠 이미 슬로시 앱 웹사이트가 있다고 치죠 slothy.example.com입니다 *글자수 검사상 16자를 넘지 않음 그리고 기존 웹사이트로 슬로스크리에이터의 문서를 발행해 보겠습니다 슬로스크리에이터 DocC 보관소 콘텐츠만 받아들여 우리 웹 서버 루트에 복사하면 slothy.example.com/ documentation/ slothcreator에 슬로스크리에이터 참조 문서가 나타납니다 슬로스크리에이터 패키지용 튜토리얼은 다 인접한 튜토리얼 경로에 있겠죠 하지만 이 경우 우리 자체 도메인을 발행하지 못해요 그 대신 GitHub 저장소에 문서를 보관하고자 GitHub Pages가 제공하는 도메인에 발행합니다 저장소용 GitHub Pages 사이트를 만들 땐 그 웹사이트 URL이 루트 경로에 있지 않죠 그 대신 저장소 이름과 일치하는 특정한 기본 경로에 있게 됩니다 대개 이런 식이죠 사용자명.github.io 그리고 사선 다음에 저장소 이름을 적습니다 참조와 튜토리얼 문서 경로는 전부 다 이 기본 경로에 첨부됩니다 여러분 저장소의 고유한 기본 경로라서 GitHub Pages 발행용 DocC 보관소를 만들기 전에 Swift-DocC에 꼭 알려야죠 Xcode 14엔 이런 사용 사례만을 위한 새로운 빌드 설정이 공개됩니다 DocC 보관소 호스팅 기본 경로 세팅을 GitHub 저장소 이름으로 설정하고 나면 앞으로 모든 문서를 작성할 준비가 될 겁니다 연습으로 이 원리를 살펴보겠습니다 Franklin이 보여 줬던 슬로스크리에이터 Swift 패키지를 열었죠 슬로시 앱에 종속된 부분입니다 이 패키지가 더 널리 쓰이게 발행할 때가 다가오니 GitHub Pages용으로 준비한 문서를 발행해 보죠 우선 프레임워크 프로젝트 설정을 엽니다 Xcode 프로젝트 탐색기로 마우스를 움직여 슬로스크리에이터 항목을 선택해서 말이죠 그리고 슬로스크리에이터 타깃을 선택하고 빌드 세팅 탭을 엽니다 Swift-DocC 관련 세팅을 찾는 경우니 DocC용으로 걸러 보겠습니다 이젠 DocC 보관소 호스팅 기본 경로 세팅을 우리 저장소 이름으로 설정하죠 '슬로스-크리에이터'입니다 잘됐네요 다음 순서로 문서를 작성해 봅니다 제 마우스를 Product 메뉴로 올리죠 그리고 문서 작성을 선택합니다 Xcode가 제 프로젝트 컴파일링과 문서 생성을 끝내면 문서 창이 열릴 겁니다 슬로스크리에이터 문서의 톱 레벨 페이지용인데 이걸 내보내 보도록 하죠 문서 탐색기와 슬로스크리에이터 기능 항목으로 제 마우스를 옮길 겁니다 그리고 컨텍스트 메뉴를 클릭하고 내보내기를 선택하죠 제 저장소 루트에 있는 'docs'란 이름의 디렉터리로 내보낼 겁니다 제 문서 웹사이트를 발행하려 GitHub Pages를 이렇게 설정해서요

이젠 GitHub에 변경한 걸 반영해 올리기만 하면 되죠 다시 Xcode의 메인 창으로 돌아가 Source Control 메뉴로 마우스를 올리고 Commit을 선택합니다 제 문서 내용이 담긴 docs 디렉터리를 선택하고 커밋 메시지를 씁니다 이제 변경 사항을 적용해 봅니다

다 됐습니다 발행 사이트를 살펴보죠 GitHub 닷컴의 제 저장소를 열겠습니다

이미 README에 문서 사이트 링크를 설치했으니 그냥 클릭해 볼게요 자, 여기 나오네요 슬로스크리에이터용으로 만든 문서가 웹에서 쉽게 접속되니 참 신나죠 프로젝트에 슬로스크리에이터를 쓰는 데 관심을 가진 분들께 굉장히 유용하리라 봅니다 슬로스크리에이터용 문서를 써 봤으니 저장소의 문서가 바뀔 때마다 활용하게끔 설정을 자동화하고 싶습니다 슬로스크리에이터를 Swift 패키지로 출시하니 새로운 Swift-DocC Swift 패키지 매니저 플러그인이 여기서 굉장히 유용할 겁니다 Swift-DocC 플러그인으로 Swift 패키지용 문서 작성 프로세스를 무척 간소화할 수 있죠 플러그인 문서 링크는 밑에 있으니 살펴보시길 권장해요 GitHub Pages에 문서 활용 자동화 설정을 시작하기 안성맞춤이니까요 다른 호스팅 서비스에서도요 그리고 Swift-DocC는 물론 꾸준히 훌륭한 Xcode 프로젝트 명령줄을 지원하죠 xcode빌드 doc빌드 명령줄 인터페이스인데 Xcode 13에서 소개됐습니다 xcode빌드로 GitHub Pages 활용을 자동화하기 시작하는 방법은 아래쪽에 링크했습니다 올해 웹에서 새롭게 Swift-DocC를 위한 강력한 브라우징과 탐색 경험을 선보이니 신나죠 슬로스크리에이터 문서 구독자들이 프레임워크가 제공하는 걸 파악하는 데 새 탐색 사이드바가 어떻게 유용한지 살펴보죠 슬로스크리에이터용 GitHub Pages로 돌아와 페이지의 왼쪽을 보면 새로운 탐색 사이드바가 있습니다 CareSchedule 항목으로 마우스를 옮겨 공개 표식을 클릭해서 확장합니다 이젠 CareSchedule의 산물로 구성된 페이지가 보입니다 페이지를 다 열어 보지 않아도요 이번엔 이 유형의 이니셜라이저로 바로 넘어가는 데 관심이 있죠 전 프레임워크를 계속 탐색하며 푸드제네레이터와 슬로스푸드 같은 다른 항목을 확장하면 결국 twig 페이지가 열립니다 페이지 사이를 탐색할 때 탐색 사이드바 상태가 그대로 유지돼서 제가 방문한 페이지를 기록해 둡니다 그래서 제가 즐기는 프레임워크를 자연스럽게 살펴볼 수 있죠 이미 슬로스크리에이터 프레임워크에 익숙하고 특정한 상징에 대한 정보를 찾을 땐 어떨까요? 새 탐색 사이드바 맨 밑에 있는 필터가 이럴 때 딱 좋죠 제 슬로스의 에너지 레벨을 증가하는 데 유용한 API에 관심이 있습니다 탐색기 맨 밑으로 제 마우스를 옮겨서 필터 바를 선택하고 '에너지'라고 입력합니다 완벽하네요 에너지 레벨 영역의 이 문서는 바로 제가 찾던 겁니다 Xcode 14의 Swift-DocC가 제공하는 새 브라우징 경험은 문서 사이트 수준을 한 단계 높일 테니 여러분이 써 보시면 참 좋겠습니다 이제 Xcode에 통합된 Swift-DocC는 여러분의 프로젝트 문서를 다 지원하죠 Xcode 프로젝트든 Swift 패키지든 앱과 프레임워크 대상의 Objective-C와 Swift 코드도 포함됩니다 Xcode 14가 제공하는 DocC 보관소는 GitHub Pages 같은 대중적인 호스팅 서비스와 즉각적으로 호환됩니다 더 많은 사람에게 문서를 배포하는 작업의 판도를 바꾸는 겁니다 마지막으로 Swift-DocC는 강력한 웹 탐색 경험을 새롭게 제공하죠 탐색 사이드바는 여러분 사이트의 문서를 조사하고 찾는 새로운 방식을 제시할 겁니다 새 Swift-DocC 사이드바와 최고의 문서 작성법을 더 배워서 이 새로운 기능을 활용하고 싶으시면 'Swift-DocC 콘텐츠 검색 향상법' 세센을 살펴보십시오 여러분의 문서 수준을 높이려면 'DocC로 쌍방향 튜토리얼 만들기' 세션을 보세요 앱과 프레임워크로 어떻게 단계적으로 개발자들에게 설명할지 배우실 수 있게요 여러분이 Xcode 14로 문서를 쓰고 발행하시는 걸 본다니 정말 기대됩니다 시청해 주셔서 감사합니다 ♪