Swift-DocC로 다채로운 문서 만들기

Swift-DocC로 다채로운 문서 만들기

Swift-DocC의 최신 기능을 활용하여 앱이나 프레임워크에서 다채롭고 자세한 문서를 만드는 방법을 배워 보세요. Xcode 15 Documentation Preview 에디터를 사용하여 효율적으로 기존 프로젝트의 문서를 반복 작업하는 방법을 보여 드리고, 그리드 기반의 레이아웃, 동영상 지원, 맞춤형 테마 등 확장된 저작 기능을 탐구합니다. 이 세션을 최대한 이해하려면 Swift-DocC 문서의 기본에 관한 실용적 지식이 있어야 합니다.

챕터
- 0:00 - Introduction and overview of Swift-DocC
- 3:33 - Building and browsing documentation in Xcode
- 6:21 - Documenting Swift extensions
- 8:05 - Activating the Documentation Preview editor
- 9:44 - Adding an image to your documentation
- 12:06 - Organizing documentation pages into Topic Groups
- 13:53 - Using Swift-DocC directives to create rich documentation pages
- 25:12 - Theming the online version of your documentation
- 28:29 - Publishing and browsing documentation on the web
- 31:02 - Quick navigation
리소스
- DocC
- - HD 비디오
  - SD 비디오
관련 비디오

WWDC23
- Xcode 15의 새로운 기능
WWDC22
- Swift-DocC 콘텐츠의 검색 가능성 향상
- Swift-DocC의 새로운 기능
WWDC21
다운로드

♪ ♪
안녕하세요 'Swift-DocC로 다채로운 문서 만들기' 세션입니다 저는 Ethan이고 Swift-DocC 팀의 엔지니어죠 Xcode 15는 Swift-DocC 문서화에 새로운 기능을 도입하여 여러분의 문서가 두드러질 뿐만 아니라 더 효과적인 도구로 독자에게 앱과 프레임워크를 알려 줄 수 있죠 Xcode 15에 새로 도입된 Documentation Preview 에디터로 Source 에디터를 벗어나지 않고 문서를 수정할 수 있죠 어서 보여 드리고 싶어요 먼저 Swift-DocC가 뭔지 빠르게 살펴보죠 Swift-DocC는 Xcode에 통합된 문서 컴파일러로 프로젝트에 관한 문서를 소스 코드와 함께 작성하고 게시하게 해 주죠 소스에 직접 주석을 작성할 수도 있고 Markdown 파일을 이용하여 고급 개념의 콘텐츠에 관한 상세한 기술 정보를 문서화할 수도 있어요 이 문서는 정적인 웹 호스팅 솔루션과 바로 호환되어 GitHub 페이지나 Netlify에 바로 게시할 수 있죠 물론 여러분의 문서는 Xcode에 내장된 문서 창에도 나타나며 Quick Help를 통해 Xcode Source 에디터에 통합돼요 따라서 여러분이 작성하는 문서가 여러분 소스 코드에 접근하는 모두에게 자동으로 제공되며 추가 작업이 필요 없죠 Xcode 13에서 Swift-DocC를 출시한 이후 Swift-DocC 프로젝트는 오픈 소스로 공개됐으며 현재 공개적으로 개발 중이에요 우리는 Swift 커뮤니티와 함께 작업하여 여러분 프로젝트의 문서화를 지원했으며 앱과 프레임워크에 대한 지원도 계속했고 Swift, Objective-C 또는 혼합하여 작성한 앱도 상관없죠 Xcode 15는 Swift-DocC 문서 작성 경험을 새로운 수준으로 끌어올려요 Documentation Preview 에디터는 여러분이 타이핑할 때마다 실시간으로 렌더링된 문서를 볼 수 있어 키를 누를 때마다 피드백을 제공하죠 새로운 저작 능력인 그리드 기반의 레이아웃과 영상 지원 맞춤형 페이지 아이콘과 완벽한 개인 맞춤형 테마를 통해 프로젝트를 제대로 대표하는 맞춤형 문서를 작성할 수 있죠 이 세션에서는 Swift-DocC의 고급 기능에 집중할게요 Swift-DocC를 처음으로 접한다면 'XCode의 DocC 문서화를 만나다'와 'Xcode로 DocC 문서화 향상'을 먼저 시청하세요 2개의 세션에서 소개하는 프레임워크의 문서화를 어떻게 개선했는지 다루고 새로운 프로젝트에 문서화 요소를 추가하는 과정을 소개하죠
먼저 Xcode 15의 Documenation Preview 에디터로 문서를 작성하는 새로운 작업 흐름을 다뤄요 새로운 에디터를 통해 새로운 Swift-DocC 기능을 활용하여 프레임워크에 대한 기존 문서를 개선할게요 다음으로 문서의 맞춤형 테마를 만들어서 기존 웹사이트와 웹 버전이 같아 보이게 작업하죠 끝으로 문서를 웹에 게시한 후에 Xcode 15로 모든 Swift-DocC 웹사이트에 적용될 새로운 탐색 기능을 살펴볼게요 바로 시작하죠
지난 2년 동안 팀원들과 함께 SlothCreator라는 Swift 패키지를 작업했죠 SlothCreator는 iOS 앱에 임포트 할 수 있는 프레임워크로 나무늘보 목록을 만들고 개인 맞춤화하는 데 사용돼요 SlothCreator가 더 많은 iOS 앱에서 이용되도록 문서를 개선하는 방법을 찾고 있었어요 Xcode 15에서 SlothCreator의 Swift 패키지를 열었죠 일단 현재 문서의 상태부터 평가할게요 Product 메뉴로 가서 Build Documentation을 선택하세요
Xcode가 문서와 함께 프로젝트를 빌드하고 문서 창을 열죠 여러분의 프로젝트에서도 할 수 있는데 Swift-DocC에 대한 문서를 작성하지 않았어도 돼요 Swift-DocC가 관련 API에 관한 페이지를 자동으로 만들며 여러분이 작성했을 문서 주석을 포함하죠 처음부터 문서화 기능이 많은 도움이 되죠 더 좋은 건 Build Documentation을 선택했을 때 Xcode가 프로젝트 의존성에 관한 문서도 제작하기 때문에 예를 들어 SlothCreator 같은 제삼자 라이브러리에 의존한다면 함께 나타날 거예요 SlothCreator의 최상위 문서 페이지죠 요약 문장으로 시작되는데 프레임워크에 관한 개요가 적혀 있어요 페이지 아래로 스크롤하여 Topics 섹션을 보죠 Topics는 문서의 여러 부분을 논리적인 그룹으로 정리하는 데 사용해요 먼저 Essentials는 프레임워크가 처음인 사람을 위한 소개 문서로 구성되죠 그리고 나무늘보 생성을 돕는 기호의 내용이 있고 나무늘보를 아끼고 먹이를 주는 내용이 이어져요 주제 그룹이 잘 정리돼 있으면 여러분의 프로젝트 문서를 쉽게 찾아서 접근할 수 있죠 참고할 만한 세션은 'Swift-DocC 콘텐츠를 쉽게 찾을 수 있도록 개선하기'로 독자들이 쉽게 문서를 검색할 수 있는 고급 기술을 배울 수 있죠 이제 Sloth 구조에 관한 문서를 열어 볼게요 지금 클릭할게요
Sloth는 문서가 잘 정리돼 있고 훌륭한 개요를 통해 관련 페이지로 연결되는 인라인 링크를 포함하며 작업을 시작할 수 있는 코드 예시가 있고 잘 정리된 Topic 그룹을 통해 관련 기호를 찾을 수 있죠 뒤로가기 버튼으로 SlothCreator의 최상위 페이지로 돌아가서 계속 페이지를 스크롤할게요 항목들이 잘 정리돼 있어 만족스러운데 페이지 맨 아래를 보면 전에는 못 봤던 기호인 SwiftUI 모듈이 있죠 이 기호가 나타나는 이유는 Xcode 15의 새로운 Swift-DocC 기능이 확장 프로그램을 지원하기 때문이죠 Xcode 15를 통해 다른 프레임워크에 속하는 확장 프로그램에 대한 내용도 문서에 담을 수 있어요 확장 프로그램은 Swift 언어의 강력한 기능으로 기존 소스 코드에 있어 접근할 수 없었던 기능을 타입에 추가할 수 있게 해 주죠 예를 들어 SwiftUI의 View 프로토콜을 확장하여 앱을 위한 추가 기능을 포함할 수 있어요 이제 확장 프로그램 기호를 여러분의 앱, 프레임워크와 함께 문서로 만들 수 있죠 새로운 기능은 전부 커뮤니티가 주도했으며 Swift-DocC와 Swift 컴파일러의 변경을 공조했어요 이 기능을 활용하여 SlothCreator의 문서를 개선해 볼게요 지금 SwiftUI 확장 모듈을 클릭할게요
SlothCreator가 SwiftUI의 Image 구조를 확장해서 확장 프로그램으로 나타나고 있죠 Image 페이지를 열면 추가된 이니셜라이저를 볼 수 있어요 이니셜라이저를 위한 문서는 기본적인 권리가 있지만 앞에서 본 Sloth 구조의 수준에 미치지 못하는군요 개선하고 싶어요 확장 프로그램이 포함된 Swift 파일을 열기 위해 ImageExtensions 파일을 Project 탐색기에서 선택할게요
그리고 Project 탐색기를 닫을게요
Sloth 기반 Image 이니셜라이저의 선언이죠
선언 바로 위에는 기호의 문서 주석이 있는데 3개의 슬래시로 정의돼 있죠 이니셜라이저에 관한 문서를 추가하고 싶은데 Xcode 15로 문서를 작성하는 가장 좋은 방법은 Documentation Preview 에디터를 사용하는 거예요 Documentation Preview 보조 에디터를 활성화하려면 에디터 옵션 메뉴를 선택하세요
그리고 Assistant 항목을 선택하세요 보조 에디터의 점프 바를 클릭하여 보조 모드를 선택한 뒤에 끝으로 Documentation Preview를 선택하세요 이제 됐습니다 Documentation Preview가 활성화를 유지하는 동안 Swift 소스 파일이나 Objective-C 헤더 파일과 Markdown 파일을 탐색할 수 있죠 SlothCreator에서도 해 볼게요
좋아요 그럼 Discussion 섹션부터 만들어 보죠 Swift-DocC는 문서 주석의 첫 번째 행을 페이지의 초록이나 요약 문장으로 사용하죠 다음 문단은 Discussion 섹션으로 사용되죠 이렇게 적을게요 '이 이니셜라이저를 사용하여' '주어진 나무늘보의 이미지를 표시하세요' Documentation Preview가 타이핑 중에 실시간으로 업데이트되어 기호에 관한 문서의 렌더링된 버전을 보여 주죠 다음으로 코드 예시를 추가하여 이니셜라이저를 사용하는 방법을 보여 드릴게요 Markdown의 코드 블록 구문으로 코드 블록부터 만들어 보죠
'swift'를 소스 언어로 지정하여 구문을 강조하는데 사용할 거예요 그리고 코드 예시를 붙여넣을게요
이 예시로 얼음 나무늘보의 이미지를 렌더링하는 SwiftUI 뷰 생성 방법을 설명하죠 예시에 UI가 수반되므로 결과가 어떤 모습인지 보여 주는 스크린샷을 추가하면 좋겠군요 데스크톱에서 준비해 둔 게 있죠
근데 문서에 스크린샷을 실제로 사용하려면 SlothCreator 문서 카탈로그에 이미지를 추가해야 해요 문서 카탈로그는 Swift 패키지와 Xcode 프로젝트에 추가할 수 있는 파일 디렉터리로 Markdown 파일이나 이미지, 영상 등의 추가 콘텐츠를 제공하게 해 주죠 더 긴 형태의 기사나 튜토리얼을 넣는 곳이에요 추가하는 모든 이미지와 영상을 문서 주석에서 참조할 수 있죠 Project 탐색기를 확장하면 SlothCreator에 이미 문서 카탈로그가 있으므로 스크린샷의 라이트와 다크 모드를 전부 드래그할게요
문서 카탈로그 어디에든 이미지를 놓으면 Swift-DocC가 찾아 주죠 이를 통해 카탈로그 정리 방식의 유연성을 확보하여 저와 제 팀에게 제일 적합한 구조를 만들 수 있어요 페이지에 이미지를 포함하고 싶을 때는 기반 파일 이름으로 이미지를 참조하면 되죠 문서 카탈로그에 있는 이미지나 다른 파일은 문서에만 사용된다는 걸 알아두시기 바랄게요 예를 들어 앱에 이미지를 추가하고 싶다면 애셋 카탈로그를 이용해야 하죠 이제 문서에 스크린샷을 추가할 준비가 됐어요 Markdown의 이미지 구문을 이용하여 설명글로 사용할 대체 텍스트와 이미지의 파일 이름을 제공하죠 여기서는 기반 파일의 이름을 사용했어요 DocC가 자동으로 라이트와 다크 모드 버전을 알아내죠 마무리 텍스트로 문서를 끝낼게요
좋네요 Documentation Preview 에디터로 기호에 대한 자세한 문서를 쉽고 재미있게 만들었어요 다음으로 이 메서드를 정리하여 페이지 최상위의 Topic 그룹에 두고 싶군요 Project 탐색기를 활성화하고 문서 카탈로그에 있는 'SlothCreator' Markdown 파일을 선택할게요 Documentation Preview 에디터가 SlothCreator 최상위 페이지의 렌더링된 콘텐츠를 보여 주고 있군요 미리보기 에디터를 이용하여 DocC 구문의 원리를 이해할 수 있어서 좋아요 예를 들어 주제 그룹이 정의된 걸 보면 2단계 Topics 헤더 아래 3단계 헤더가 있죠 페이지를 주제 그룹에 넣으려면 3단계 헤더 중 하나의 아래에 목록 항목을 생성하고 페이지와 연결하세요 확장된 SwiftUI Image 타입에 이 작업을 진행하죠 Image 확장 프로그램으로 UI의 나무늘보를 보여 주므로 Sloth Views 주제 그룹에 있는 나무늘보 렌더링과 관련된 기호에 넣으면 되겠군요 그곳으로 연결할게요 코드 자동 완성이 타입 참조를 제공하여 도와주죠
좋습니다, 이제 SlothCreator의 Image 확장 프로그램 문서가 제대로 기록됐고 잘 정리됐군요 SlothCreator를 위한 문서를 처음 게시한 이후 프레임워크의 기반을 시현하는 샘플 코드 프로젝트를 요청하는 피드백을 받았죠 피드백을 반영하여 Slothy라는 앱을 만들었는데 SlothCreator에 의존하죠 제 동료가 이미 SlothCreator의 주요 문서에 포함할 초안을 작성했는데 새로운 Slothy 샘플로 연결되는 기능도 있어요 한번 살펴보죠 일단 문서의 초안을 SlothCreator의 문서 카탈로그에 추가할게요
여기 있는 콘텐츠는 이미 훌륭하죠 같은 앱의 여러 기능을 안내하며 앱의 스크린샷도 포함하고 샘플을 다운로드할 수 있는 저장소의 링크도 있죠 근데 더 개선할 수 있어요 새로운 Swift-DocC 기능을 이용하면 되죠 Swift-DocC의 저작 구문은 Markdown 위에 구축돼 있어요 Markdown이 익숙하다면 콘텐츠의 서식인 링크, 이미지 굵고 기울어진 텍스트와 표도 작업할 수 있을 거예요 Swift-DocC는 지시문으로 기본 Markdown 구문을 확장하여 여러분의 문서를 위해 특별히 만들어진 기능을 활용할 수 있게 해 주죠
이제 그 지시문들을 사용하여 Slothy 샘플 코드 문서를 다듬을 건데 이런 지시문들은 창의적으로 사용할 수 있다는 걸 기억하세요 맞는 방법이 하나뿐이지 않고 사용에 적합한 페이지가 있는 것도 아니에요 여러분만의 방식으로 지시문을 사용하여 프로젝트에 관한 문서의 이해도를 높이고 몰입감과 재미를 선사하세요 문서의 레이아웃을 편집하기 전에 구체적인 문제부터 식별할게요 그렇게 하면 새로운 지시문을 채택하여 문서가 개선될 거라는 걸 확신할 수 있죠 제일 먼저 눈에 띄는 건 눈에 띄지 않는 요소예요 이 페이지는 다른 문서와 똑같이 양식화돼 있는데 다른 문서와 달리 독자가 관심을 보일 만한 샘플 코드가 있죠 그 점을 생각하면 이 문서의 제일 중요한 점은 샘플 코드의 소스 저장소로 연결하는 겁니다 근데 샘플 코드 링크를 알아보거나 찾기 힘들죠 문서의 본문 내용으로 넘어갈게요 2개의 이미지-문단 쌍을 중심으로 구성된 콘텐츠죠 각 문단이 관련 이미지를 설명하죠 여기 문제가 2개 있어요 먼저 이미지가 문단과 명확히 연결돼 있지 않고 둘째, 이미지가 너무 많은 공간을 차지해요 여기 있는 이미지가 각 문단을 강조해야 하는데 그 자체로는 흥미롭지 않죠
끝으로 페이지 아래로 내려가면 SlothCreator의 현지화 지원을 설명하죠 같은 스크린샷이 3개의 다른 버전과 3개의 언어로 쓰여 있어요 근데 수직으로 배치돼 있어 현지화를 설명한 문단과의 연관성이 안 보이네요 시각적으로도 너무 많은 공간을 차지하죠 Swift-DocC로 4가지 문제를 어떻게 해결할지 살펴볼게요 문서의 본문 내용부터 시작하죠 이미지와 문단을 적절하게 짝지으려면 그리드에 배치해야 해요 이미지보다 문단이 중요하다는 걸 강조할 수 있고 이미지와 관련 문단이 더 잘 연결되죠 Swift-DocC의 그리드는 유연한 행과 열로 정의돼요 먼저 2개의 열을 포함하는 행을 정의할게요
이후에 문단을 첫 번째 열에 배치하고 이미지는 두 번째 열에 배치하는 거죠
이제 이미지와 관련 문단이 훨씬 더 연관된 느낌인데 이 경우에는 문단이 이미지보다 우선해야 하죠 문단을 포함하는 열의 크기를 증가시켜 볼게요 첫 번째 열에 크기 매개변수를 추가하고 기본값인 1보다 큰 값을 지정하면 되죠 크기 매개변수를 이용하여 특정 열의 폭을 설정할게요 저는 크기를 3으로 지정할게요
열이 4개인 그리드에서 첫 열이 3개의 열을 차지하는군요 너무 큰 것 같아요 크기가 2면 어떨까요?
텍스트와 이미지의 균형이 좋아 보이네요 좋아요 이제 두 번째 문단과 이미지에도 같은 설정을 적용하죠
훨씬 나아 보이지만 페이지의 균형이 맞지 않는 느낌이죠 이미지와 문단의 위치를 바꿀게요
좋아요 문서가 모양을 잡아가는군요 현지화 섹션에서 발견했던 문제는 이미지가 수직 공간을 너무 많이 차지하여 맥락이 끊긴다는 거였죠 이럴 땐 탭 탐색기가 완벽한 해결책인데 다수의 요소를 하나로 압축할 수 있죠 시험해 볼게요
3개의 탭으로 탭 탐색기의 초기 구조를 만들게요
탭 탐색기는 TabNavigator 지시문을 포함하여 정의되며 임의의 수의 자식 Tab 지시문을 포함하죠 각 탭은 매개변수로 이름을 제공해요 3개의 이미지를 각 탭에 배치하도록 하죠
이제 독자가 탭을 클릭하여 관심 있는 스크린샷을 열어 볼 수 있어요
한 단계 더 나아가서 영상을 추가할 건데 독자들의 관심을 끌고 샘플에 열광하게 할 내용이죠 Swift-DocC에서 제공하는 동영상 지시문을 추가할게요
동영상이 재생되기 전에 표시될 대표 이미지와 동영상 설명글을 제공하도록 하죠
좋아요 이제 개요 섹션으로 이동하죠 제일 먼저 발견했던 문제는 샘플의 소스 코드 저장소의 링크를 찾는 게 힘들다는 거였는데 Swift-DocC에 이 문제를 해결해 줄 콜투액션 지시문이 있죠 페이지의 제일 위에 메타데이터 컨테이너 지시문을 추가할게요 메타데이터 지시문으로 추가 정보를 지정했는데 페이지에는 직접 렌더링되지 않죠 이 경우에는 페이지에 콜투액션을 첨부하려고 해요
목적지 URL과 콜투액션의 목적을 제공했죠 여기서는 'link' 목적을 사용했어요 바로 다운로드가 시작된다면 'download'를 쓸 수도 있지만 이 경우는 소스 저장소를 링크하는 경우이므로 'link'가 더 적합하죠 끝으로 SlothCreator 문서의 다른 부분보다 이 부분이 두드러지는 걸 원해요 이 페이지에 샘플 코드가 있는 걸 독자들이 놓치지 않길 바라요 Swift-DocC는 샘플 코드를 포함하는 문서를 위한 특별한 지원을 하죠 제 페이지가 샘플 코드라는 걸 지정하기 위해 'sample code' 인자와 함께 PageKind 지시문을 제공할게요 렌더링된 페이지는 'Sample Code' 제목 헤더가 있고 중괄호 페이지 아이콘으로 샘플 코드 문서라는 걸 강조하죠 현재 Swift-DocC에는 PageKind 지시문을 위한 2개의 값을 지원하는데 'article'과 'sample code'죠 여러분이 관심 있는 페이지 종류도 의견으로 전달해 주세요 Swift-DocC는 오픈 소스 프로젝트이므로 Swift Forums에서 이런 주제를 논의하기 좋고 DocC가 여러분 문서에 도움이 될 만한 다른 피드백이나 아이디어를 나눌 수도 있죠
SlothCreator를 자신의 앱에 이용하는 개발자들은 이 문서를 아주 좋아할 거예요 몰입하게 되고 편리하며 재미있죠 이 문서를 찾을 수 있도록 SlothCreator의 최상위 페이지로 돌아가서 잘 보이는 곳에 링크를 배치하죠
먼저 새로운 문서를 Topic 그룹에 넣을게요 이 경우에는 Essentials 그룹이 제일 적절하죠 SlothCreator 프레임워크에 새로 오는 사람들은 Slothy 샘플에 관심이 있을 테니까요
시작이 좋지만 한 단계 더 나아가서 페이지의 일반 주제 섹션 위에 배치하는 게 좋을 것 같아요 Links 지시문이 이 경우에 완벽하죠 Featured 섹션을 만들고 Links 지시문을 넣을게요
Links는 페이지를 강조하는 데 효과적입니다 Links로 카드 이미지와 페이지 설명글을 추가하면 향상된 느낌을 줄 수 있죠 Links 지시문은 시각적 양식 매개변수를 받아들이며 링크가 렌더링되는 방식을 정의하고 본문에는 Topic 그룹처럼 링크 목록이 있어요 Slothy 샘플로 링크를 연결할게요
Links는 다양한 시각적 스타일을 지원하는데 기본적인 목록은 주제 섹션의 기본 양식처럼 렌더링되며 상세 그리드도 가능하죠
그리드 양식이 더 낫지만 Slothy 샘플을 대표할 수 있는 맞춤형 이미지를 추가할게요 다시 Slothy의 Markdown으로 돌아가죠 Slothy 문서를 그리드 기반의 Links 섹션에 제일 멋진 방식으로 보여 주려면 메타데이터에 페이지 이미지를 제공해야 해요 지금 그걸 하죠
'card'의 목적을 지정하여 Slothy 문서가 카드로 렌더링될 때마다 사용되도록 하고 이미지의 소스와 설명글로 쓸 대체 텍스트를 제공할게요 SlothCreator의 최상위 페이지로 돌아가면
Slothy가 맞춤형 페이지 이미지로 렌더링되어 있죠 'Sloth로 시작하기' 문서도 함께 표시하죠
마무리로 최상위 페이지에 메타데이터를 추가할게요 이전에 했던 것처럼 Metadata 지시문부터 생성할게요 그리고 페이지 이미지를 제공해요
이번에는 'card' 대신 'icon' 목적을 지정했죠 이 이미지는 페이지의 아이콘이 렌더링될 때마다 사용되며 내비게이션 사이드바와 페이지 개요 섹션에도 포함돼 있죠 끝으로 맞춤형 페이지 색을 설정할게요
기본적으로 페이지 최상단은 파란색을 사용하는데 Swift-DocC에 내장된 기본 색상이 여러 개 있죠 노란색이나 보라색 주황색이 있어요 SlothCreator는 강조 색으로 초록색을 사용하므로 여기에도 초록색을 사용하여 일관적인 경험을 제공하면 좋겠죠
놀라워요 SlothCreator의 문서가 짧은 시간에 많이 바뀌었죠 레이아웃 지시문인 Row와 Column Tab Navigator와 Video를 사용하여 샘플 코드 문서의 흐름이 나아졌고 독자의 몰입도를 높였어요 메타데이터 지시문인 CallToAction과 PageKind로 세련된 느낌을 추가했죠 그리고 Links 지시문으로 추천 콘텐츠를 개선하여 모든 내용을 하나로 묶고 페이지 최상위에 PageColor와 PageImage 지시문으로 브랜드의 특성을 추가했어요 SlothCreator의 새 문서를 공유하게 되어 기쁘군요 근데 새로운 버전을 웹에 게시하기 전에 맞춤형 테마를 이용하여 SlothCreator의 문서를 온라인에 최적화할게요 더 큰 제품 웹사이트의 일부로 SlothCreator 문서를 게시하죠 저는 문서 사이트가 제품 사이트와 시각적 일관성을 유지하도록 같은 색감과 폰트를 사용하려고 해요 Swift-DocC의 맞춤형 테마로 목표를 달성하는 법을 살펴보죠 Swift-DocC는 시각적 스타일링의 개인 맞춤화를 지원하며 배포되는 문서 사이트의 색상, 테두리, 아이콘과 폰트를 조절할 수 있죠 이러한 맞춤화를 작업하는 특수 JSON 파일을 문서 카탈로그에 추가하면 여러분의 문서 사이트가 다른 사이트에 제대로 통합될 수 있도록 해요 Swift-DocC의 테마 도구로 특정 기업 스타일에 맞추거나 마케팅 사이트, 개인 블로그에 맞출 수도 있어요 다만, 여러분이 맞춤화하려는 모든 문서에 테마 편집이 적절하진 않죠 예를 들어 SlothCreator의 샘플 코드 페이지처럼 특정 페이지의 모습을 개인 맞춤화할 때 맞춤형 테마가 아닌 해당 페이지의 지시문을 사용해야 해요 테마 맞춤화는 개별 페이지가 아닌 사이트 전체에 걸쳐 진행하죠 또한 Swift-DocC의 테마는 배포에만 초점을 맞추지 않았어요 만약 Xcode에서 문서를 열면 여러분의 문서는 계속 Xcode 테마로 렌더링되어 나머지 문서와 함께 어울리는 모습으로 표시될 거예요 따라서 웹상의 맞춤형 테마에만 집중하고 Xcode에서 어떻게 나타날지 걱정하지 않아도 되죠 대신 Xcode와 웹 모두 맞춤형 테마를 적용하고 싶다면 그 작업에 필요한 지시문을 사용해야 하죠 SlothCreator의 맞춤형 테마를 살펴볼게요 Swift-DocC 테마는 JSON 파일로 정의되며 이름은 theme-settings.json이고 이 파일을 프로젝트의 문서 카탈로그에 넣어야 해요 테마 설정 파일에는 여러분이 만들 수 있는 다양한 맞춤 설정이 있죠 SlothCreator는 사이트의 색상과 폰트만 맞춤화할게요 이 맞춤화 설정은 각각 'color'와 'typography' 섹션에 들어가죠
SlothCreator는 마케팅 자료에 특정한 초록색을 사용해요 SlothCreator의 최상위 페이지는 PageColor 지시문을 통해 초록색으로 설정했죠 이제 'standard-green' 색상 변수를 이용하여 제가 원하는 초록색으로 설정할 수 있어요 SlothCreator는 진지한 프레임워크고 진지하게 게으른 전문가를 겨냥하므로 온라인 문서의 폰트를 Serif로 사용할게요 'html-font' 글꼴 변수를 사용하면 되죠 물론 이런 개인 맞춤화는 Swift-DocC 테마 작업의 시작일 뿐이에요 자세한 내용이 궁금하면 Swift-DocC 문서를 읽어 보세요 이제 theme-settings.json 파일을 설정했으니 문서 카탈로그에 추가할게요
SlothCreator의 소스 제어 저장소는 'xcodebuild' 명령행 도구를 쓰는 지속 통합이 설정돼 있어 우리가 새로운 커밋을 내보낼 때마다 SlothCreator의 문서를 빌드하고 배포하죠 이는 훌륭한 작업 흐름으로 문서가 프레임워크의 최신 사항을 반영하도록 해요 만약 여러분의 프로젝트에도 비슷한 작업 흐름을 원한다면 Xcode 문서의 Swift-DocC 섹션을 살펴보세요 우리가 만든 변경 사항을 게시하게 되어 기쁘군요 이제 커밋과 푸시를 통해 새 버전을 웹사이트에 배포하죠 Xcode 창의 왼쪽 상단으로 마우스를 움직여 Source Control 탐색기를 활성화할게요 모든 변동 사항을 올린 뒤
커밋 메시지를 추가하고 커밋, 푸시할게요
이제 SlothCreator의 웹사이트를 열어 보죠 SlothCreator 제품 사이트의 홈페이지예요 SlothCreator의 브랜드에 맞는 폰트와 색상을 사용하죠 '문서 읽어 보기' 버튼을 클릭할게요
SlothCreator의 문서예요 우리의 맞춤형 테마가 웹사이트 버전에 적용됐고 특유의 폰트와 초록색을 사용했죠 우리가 설정한 맞춤형 아이콘도 있고 참고 섹션에는 새로운 Slothy의 샘플 코드가 있어요 '샘플 코드 보기' 링크를 클릭하여 열게요 문서의 완성된 모습이 아주 만족스럽군요 물론 Swift-DocC 웹사이트는 멋진 내비게이션 사이드바도 있어서 제가 구성한 SlothCreator의 Topic 섹션을 쉽게 탐색할 수 있죠 맨 위에 Essentials 그룹이 있는데 Slothy 샘플 코드 문서를 배치했던 곳으로 '새로 시작하기' 문서와 Sloth 구조체가 함께 있죠 왼쪽의 펼쳐보기 아이콘으로 Sloth 구조체를 펼칠게요 이제 구조체의 자식들을 탐색할 수 있는데 기호들이 주제 그룹 안에 잘 정리돼 있어요 아까 문서화했던 Image 이니셜라이저를 확인해 보죠 Sloth Views 섹션을 아래로 스크롤하고 Image 확장 기호를 펼친 뒤 이니셜라이저를 클릭하세요 여기 있군요 내비게이션 사이드바가 문서 저작자에게 직관적인 탐색 경험을 제공하여 제 프로젝트의 API를 살펴볼 수 있어서 좋죠 문서를 읽는 사람의 입장에서도 어떤 페이지를 원하는지 알고 있을 때 바로 이동할 수 있는 방법이 필요해요 Xcode 15로 빌드한 Swift-DocC 웹사이트의 새로운 탐색 기능으로 페이지를 순식간에 이동할 수 있어요 Swift-DocC Quick Navigation도 커뮤니티가 주도한 기능으로 모든 Swift-DocC 웹사이트에 적용하였죠 Xcode의 Open Quickly 기능처럼 키보드 단축키를 활성화하고 이름을 입력하면 페이지로 바로 이동해요 사용해 보죠 shift-command-O를 눌러 빠른 탐색을 활성화하세요
SlothCreator 문서 내 모든 페이지의 내용을 즉시 필터링할 수 있죠 예를 들어 '시작하기' 문서를 찾고 있다면 '시작'을 타이핑하면 돼요
여기 있군요 오른쪽에 문서의 미리보기도 제공되죠
엔터 키를 눌러 페이지로 이동할게요
갑자기 나무늘보의 능력이 어땠는지 알고 싶군요 다시 shift-command-O를 누르고 '능력'을 입력하세요
PowerPicker가 있고 power 프로퍼티도 있군요 여기 있습니다 Power 이넘이죠 이번에는 '더 보기' 링크를 클릭해 페이지를 열어 보죠
이제 나무늘보의 능력에 관해 읽을 수 있어요 Quick Navigation 팝업 창과 기존의 내비게이션 사이드바로 Swift-DocC가 문서 탐색 경험을 매끄럽게 개선했죠 Xcode 15의 Swift-DocC에 강력한 도구가 추가되어 독특한 문서 웹사이트를 만들 수 있어요 Documentation Preview 에디터를 사용해 보세요 다양한 페이지 레이아웃을 탐색해 보고 어떻게 렌더링되는지 실시간으로 볼 수 있죠 새로운 지시문인 Row, Column과 Links, PageImage를 통해 눈에 띄고 프로젝트에 어울리는 문서를 만들 수 있죠 문서 웹 버전에 맞춤형 테마를 추가하여 프로젝트의 브랜드나 온라인 이미지에 맞게 제작하는 것도 고려해 보세요 Swift-DocC의 최신 사항을 알아보고 싶다면 WWDC22의 세션인 'Swift-DocC의 새로운 사항'을 시청하세요 이 세션은 Xcode 14에 출시했던 새로운 게시 흐름을 깊게 다뤄서 GitHub와 같은 호스팅 서비스에 게시하는 방법을 알려 주죠 단계별 튜토리얼을 통해 문서를 더욱 발전시키는 것에 관심이 있다면 'DocC로 상호 작용적 튜토리얼 구축하기'를 시청하세요 어서 여러분이 Swift-DocC와 Xcode 15를 이용하여 디자인하고 게시한 문서를 보고 싶어요 감사합니다 ♪ ♪

import SwiftUI

/// An extension that facilitates the display of sloths in user interfaces.
public extension Image {
    /// Create an image from the given sloth.
    ///
    /// Use this initializer to display an image representation of a
    /// given sloth.
    ///
    /// ```swift
    /// let iceSloth = Sloth(name: "Super Sloth", color: .blue, power: .ice)
    ///
    /// var body: some View {
    ///     Image(iceSloth)
    ///         .resizable()
    ///         .aspectRatio(contentMode: .fit)
    ///     Text(iceSloth.name)
    /// }
    /// ```
    ///
    /// ![A screenshot of an ice sloth, with the text Super Sloth underneath.](iceSloth)
    ///
    /// This initializer is useful for displaying static sloth images.
    /// To create an interactive view containing a sloth, use ``SlothView``.
    init(_ sloth: Sloth) {
        self.init("\(sloth.power)-sloth")
    }
}

16:31 - Creating a grid-based layout

@Row {
    @Column(size: 2) {
        First, you customize your sloth by picking its 
        ``Sloth/power-swift.property``. The power of your sloth influences
        its abilities and how well they cope in their environment. The app
        displays a picker view that showcases the available powers and
        previews your sloth for the selected power.
    }
    
    @Column {
        ![A screenshot of the power picker user interface with four powers displayed – ice, fire, wind, and lightning](slothy-powerPicker)
    }
}

@Row {
    @Column {
        ![A screenshot of the sloth status user interface that indicates the the amount of sleep, fun, and exercise a given sloth is in need of.](slothy-status)
    }
    
    @Column(size: 2) {
        Once you've customized your sloth, it's ready to ready to thrive.
        You'll find that sloths will happily munch on a leaf, but may not be as 
        receptive to working out. Use the activity picker to send some
        encouragement.
    }
}

18:16 - Creating a tab navigator

@TabNavigator {
    @Tab("English") {
        ![Two screenshots showing the Slothy app rendering with English language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_eng)
    }
    
    @Tab("Chinese") {
        ![Two screenshots showing the Slothy app rendering with Chinese language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_zh)
    }
    
    @Tab("Spanish") {
        ![Two screenshots showing the Slothy app rendering with Spanish language content. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.](slothy-localization_es)
    }
}

19:07 - Adding a video

@Video(poster: "slothy-hero-poster", source: "slothy-hero", alt: "An animated video showing two screens in the Slothy app. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.")

19:50 - Specifying a page's "Call to Action" link

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
}

20:29 - Specifying a page's kind as "Sample Code"

@Metadata {
    @CallToAction(purpose: link, url: "https://example.com/slothy-repository")
    @PageKind(sampleCode)
}

21:55 - Using the "Links" directive to feature content

@Links(visualStyle: detailedGrid) {
    - <doc:GettingStarted>
    - <doc:SlothySample>
}

22:55 - Specifying a page's card image

@Metadata {
    @PageImage(
        purpose: card, 
        source: "slothy-card", 
        alt: "Two screenshots showing the Slothy app. The first screenshot shows a sloth map and the second screenshot shows a sloth power picker.")
}

23:41 - Specifying a page's icon image

@Metadata {
    @PageImage(
        purpose: icon, 
        source: "slothCreator-icon", 
        alt: "A technology icon representing the SlothCreator framework.")
}

23:42 - Specifying a page's color
```
@Metadata {
    @PageColor(green)
}
```

27:04 - theme-settings.json

{
    "theme": {
        "color": {
            "standard-green": "#83ac38"
        },
        "typography": {
            "html-font": "serif"
        }
    }
}

찾고 계신 콘텐츠가 있나요? 위에 주제를 입력하고 원하는 내용을 바로 검색해 보세요.

쿼리를 제출하는 중에 오류가 발생했습니다. 인터넷 연결을 확인하고 다시 시도해 주세요.

챕터

리소스

관련 비디오

WWDC23

WWDC22

WWDC21