[Swift DocC] 문서 만들기 02 - Article(설명 글) 만들기

Swift DocC

 

이번 글에서는 앱, 프레임워크의 전체적인 설명 글을 담당하는 Article을 만들어 보겠습니다. Swift DocC 시리즈는 WWDC 2023을 기준으로 나온 기능을 포함합니다.

 

 

앞선 글에서 설명했듯이 Swift DocC에는 Reference, Article, Tutorial이 있습니다. DocC 개념을 확인하거나 코드를 설명하는 Reference를 작성하는 법은 지난 글들을 참고해주세요.

 

Swift DocC 개념

Swift DocC Reference 만들기

 

 

 

Article이란?

https://developer.apple.com/documentation/Xcode/documenting-apps-frameworks-and-packages

 

WWDC 2021 - Meet DocC documentation in Xcode의 내용에 따르면 Article은 "사용자에게 프레임워크 뒤에 있는 큰 그림을 보여줄 수 있으므로 프레임워크의 개별 항목을 통합적인 스토리로 연결할 수 있다"라고 합니다.

 

직역을 해서 조금 난해하긴한데 쉽게 설명하자면 앱, 프로젝트를 위한 전체적인 설명 문서입니다. Readme.md 파일과 마찬가지로 Markdown 문법을 사용해 작성하고 그 역할도 거의 같습니다.

 

다른 점이 있다면

• 공식문서와 같은 스타일 제공
• 프로젝트 코드와 연동
• 다크모드 지원

등이 있겠네요.

 

 

 

이제 Reference를 만들었던 프로젝트로 Article을 만들어 보겠습니다.

 

작업 환경

• macOS 13.4
• Xcode 15.0 beta 2 

 

Documentation Catalog

Article을 만들기 위해서는 Documentation Catlog 파일을 생성해줘야 합니다.

 

File - New - File 을 통해 새 파일을 생성합니다. (단축키 Cmd + N)

 

Documentation Catalog

 

Documenatation - Documentation Catalog를 선택해줍니다.

 

 

파일 이름은 프로젝트와 동일하게 해줬습니다.

 

 

+프로젝트 생성 시에 Include Documentation을 통해 문서를 같이 생성해 줄 수도 있습니다.

 

프로젝트 생성시 - Include Documentation

 

생성을 완료하면 책꽂이 아이콘 파일을 확인할 수 있습니다.

 

 

가장 메인 파일인 책 모양 Electronics-View를 선택해주면 아래와 같이 Markdown 형식의 파일을 확인할 수 있습니다.

 

생성 완료

 

이제 내용을 적어보겠습니다.

 

 

Summary에 내용을 적어보겠습니다. 적고 나서 Build Documentation을 했습니다. (단축키 Cmd + Shift + Ctrl + D)

 

 

문서(Documentation)이 뜨면 바로 Article 페이지가 뜹니다. 작성한 메시지가 잘 뜨네요.

 

 

이번엔 이미지를 추가해주겠습니다. 이미지의 경우 다크모드를 지원하기 때문에 각 이미지에 대해 2개의 이미지를 넣어줘야 합니다.

 

파일 형식

 

파일 형식은 Asset의 이미지 파일 형식과 동일하게 "파일 이름 + 다크모드 여부 + 배율 + 파일 확장자" 입니다. WWDC에서는 2배의 배율을 추천하고 있네요.

 

라이트모드 파일이 apple-electronics-set@2x.png 라면 apple-electronics-set~dark@2x.png가 되겠네요.

 

 

이미지 파일을 Documentation Catalog - Resources 폴더에 위치해주었습니다. 꼭 Resources 폴더에 위치시켜야 되나 싶어서 밖에 위치 시켜줘봤는데 빌드는 잘 됐습니다. 그래도 관리의 편의를 위해서 Resources 폴더 안에 위치해주는게 좋아보입니다.

 

Markdown 이미지

 

 Markdown 문법을 사용해 이미지를 불러오면 됩니다. 여기서 주의할 건 @2x 를 빼줘야 합니다. 왜 파일 인식을 못하나 했는데 @2x 가 들어가 있으면 안됐네요.

 



이미지 추가를 완료하고 문서 빌드를 다시 해주면

 

 

라이트모드, 다크모드에서 각각 이미지를 확인할 수 있습니다.

 

 

 

 

Swift DocC Attribute

이미지가 들어간건 좋은데 뭔가 디자인이 구리다는 느낌을 버릴 수 없습니다.... 그래서 WWDC 2023- Create rich documentation with Swift-DocC에서 DocC를 위한 Attribute 기능이 추가가 되었습니다!

 

 

@를 사용해 다양한 기능을 지원합니다. @Row, @Video, @TabNavigator, @Metadata, @Links 등이 있습니다. 하나씩 확인해보겠습니다.

 

 

@Row

@Row는 문서 항목(이미지, 텍스트) 등을 가로로 정렬할 수 있게 해줍니다. @Row 안에 @Column을 사용해 세로 설정을 해줍니다.

 

 

size를 인자로 받아 @Column의 크기를 정해줍니다. size의 기본 값은 1 입니다.

 

위 코드의 경우 이미지 가로 길이가 1이면 텍스트가 3이 됩니다.

 

 

훨씬 깔끔해졌네요!

 

@TabNavigator

이번엔 @TabNavigator를 사용해보겠습니다. 현재 예제 프로젝트에 4개의 set가 있습니다. 각각의 세트를 OverView에 추가해주겠습니다.

 

 

markdown 문법에 맞춰 이미지를 추가해주면

 

 

이렇게 확인이 가능합니다! 근데 직감적으로 이 디자인도 별로라는게 느껴지시죠??? Tab 바를 사용해서 바꿔보겠습니다.

 

 

@TabNavigator 안에 @Tab을 사용해 각각의 탭 안에 들어갈 내용을 채워주면 됩니다.

 

 

 

탭 버튼이 생기며 훨씬 깔끔해졌습니다!

 

 

 

이 외에도 WWDC에 나온 것처럼 각 언어별 탭 바를 제공해줄 수도 있습니다.

언어별 이미지 지원

 

 

 

@Metadata

메타데이터는 현재 Article 페이지에 없는 추가 정보를 제공하거나, 페이지 이미지를 꾸밀 수 있게 도와줍니다.

 

 

@PageImage와 @PageColor를 통해 문서 헤더를 꾸며줄 수 있습니다.

 

@PageImage, @PageColor

 

 

배경색은 오렌지, 아이콘은 애플로고로 바꿔줬습니다.

 

 

 

@CallToAction을 사용해 버튼을 추가해줄 수도 있습니다.

 

근데 이게 렉이 걸린건지 베타 버전이라 그런건지는 몰라도 현재 제 프로젝트에서는 적용이 안되더라구요... 😅 그래서 WWDC2023에 나온 코드로 대체하겠습니다. (23년 7월 6일 - Xcode 15 beta 2 기준)

 

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

 

코드를 입력해주면

 

 

 

우측에 보이는 것처럼 Visit 버튼이 생깁니다. 눌러서 이동할 수 있는 링크나, 프로젝트 파일을 위한 링크를 버튼에 제공 할 수 있습니다.

 

 

 

@Links

@Links는 프로젝튼 내 다른 Article 파일로 링크하는 걸 다양한 디자인으로 보여줍니다. 링크 예시를 위한 새로운 Article 파일을 만들겠습니다.

 

 

Documentation - Article File을 선택해서 만들어줍니다.

 

새로운 Article

 

LinkExample이라는 새로운 Article 파일을 만들어주었습니다.

 

 

기존 Article에서 링크를 걸어주고 싶다면 <doc:파일이름> 을 해주면 됩니다. 위 예시 같은 경우는 <doc:LinkExample>가 되겠네요.

 

메인 Article 파일

 

 

 

 

위 이미지와 같이 링크가 생기고 누르면 해당 Article로 이동합니다. (preview에서는 동작 안 하네요)

 

 

 

@Links를 써서 조금 더 공식문서 같이 만들어보겠습니다. @Links는 visualStyle을 인자로 받습니다. 현재는 list, compactGrid, detailedGrid 이렇게 3가지가 있네요. 공식 문서에서 인자 확인하기

 

 

@Links(visualStyle: list) {
    - <doc:LinkExample>
}

 

위 코드와 같이 작성해주는데 이 때 주의할 점은 <doc:LinkExample> 앞 에 반드시 - 를 붙여줘야 합니다.

 

 

list

list

list의 경우 문서 아이콘 + 제목 + Summary를 확인할 수 있습니다.

 

 

compactGrid

compactGrid

이미지 + 제목을 확인할 수 있습니다.

 

 

detailedGrid

detailedGrid

이미지 + 제목 + Summary + 링크 버튼을 확인할 수 있습니다. compactGrid에서 Summary + 링크가 추가되었네요.

 

 

 

+ @Metadata, @PageImage

만약 @Links에서 이미지를 추가하고 싶다면 @Metadata 안에 @PageImage를 추가해주면 됩니다.

 

 

LinkExample 파일에 아래 코드를 추가해줍니다.

@Metadata {
    @PageImage(purpose: card, source: "Apple-Logo", alt: "애플 로고")
}

 

그리고 @Links를 확인하면

 

이미지가 들어간 링크를 확인할 수 있습니다.

 

 

 

이 외에 @Video, @Small, @SupportedLanguage 등 더 다양한 기능들은 공홈에서 확인 가능합니다.

 

 

API Documentation | Apple Developer Documentation

 

 

Topics

Topics의 경우 해당 문서와 관련된 내용을 확인할 수 있습니다.

 

Markdown 문법을 사용해 조금 더 분류해주겠습니다.

## Topics

### View

- ``ElectronicsView``

### Set 종류

- ``Electronics``

 

Preview에서는 코드에 있는 Topic만 확인이 가능한데, 문서를 빌드하면 다 뜨네요. 에러인건지 원래 이런건지;;

 

 

 

좌 - Documentation Build 시, preview로 볼 때

 

 

 

 

Extensions

현재는 소규모 프로젝트라 문서 파일이 작지만, 프로젝트가 커질수록 문서가 길어집니다.

 

특히 코드에 주석을 달아 문서를 만들게 되는데 주석 때문에 가독성이 떨어질 수 있습니다. 이를 위해 Swift DocC에서는 파일 분리를 위한 Extensions 기능을 지원합니다!

 

코드 문서

 

위 이미지에 보이는 것처럼 기존에 .swift파일에 있던 주석을 md 파일로 옮겨 코드를 깔끔하게 관리할 수 있습니다.

 

 

 

 

File - Documentation에서 Extension File을 생성합니다.

 

저는 ElectronicsView.swift 내용을 옮겨올 것이기 때문에 파일 이름을 ElectronicsView로 해주었습니다.

 

위 주석을 옮겨옵니다.

 

가장 메인 Article의 제목을 가져와야 합니다. 

 

메인 Article

 

제 제목은 Electronics_View입니다. Electronics-View로 하고 싶었는데 -를 사용하면 빌드가 안돼서 헷갈리지만 어쩔 수 없이 _를 사용했습니다.

 

 

Extension file 제목에 제목/파일이름을 작성해주시면 됩니다. 예시로 보면 Electronics_View/ElectronicsView입니다.

 

 

 

내용을 작성하고 기존  ElectronicsView.swift 파일을 주석을 제거해주었습니다. 빌드를 실행하면

 

 

주석이 잘 옮겨와 진 것을 확인할 수 있습니다. 또 Topics에 적은 Crating a ElectronicsView도 잘 적용됬네요 👏

 

 

 

 

 

정리

예제 프로젝트를 통해 Article을 작성하는 법을 공부해봤습니다. 단순한 markdown 문법뿐만 아니라 여러 기능을 추가해 더 풍부한 문서를 만들 수 있었습니다.

 

 

다음에 하는 프로젝트에서는 DocC를 사용해 깔끔한 문서 작성을 시도해봐야겠습니다. (이러고 시간에 쫓겨서 못 하겠지만... 😂)

 

 

다음 글에서는 DocC의 마지막 기능인 Tutorials를 만들어보겠습니다.

 

 

[Swift DocC] 문서 만들기 03 - 튜토리얼

 

 

Article 만들기 끝 ~~~~~ 끝

 

 

출처

Elevate your DocC documentation in Xcode - WWDC21 - Videos - Apple Developer

 

Create rich documentation with Swift-DocC - WWDC23 - Videos - Apple Developer

 

Documenting apps, frameworks, and packages | Apple Developer Documentation