[Swift DocC] 문서 만들기 04 - Github 배포

지난 글에서 Swift DocC를 사용해 튜토리얼을 만들었습니다. 이번 글에서는 지난 글들에서 Swift DocC를 통해 만든 프로젝트 문서를 배포해보도록 하겠습니다.

 

아직 문서를 만들지 않은 상태라면 이전 글을 보고 만들고 오시길 바랍니다!

 

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

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

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

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

 

 

 

시작

Swift DocC가 처음 나왔을 때는 문서 파일을 직접 호스팅해줘야 했습니다. 1년 후 WWDC 2021 - What's new in Swift-DocC에서 Github Pages를 사용해 손쉽게 배포할 수 있는 기능이 추가되었고 Github Repository에서 손쉽게 관리할 수 있게 되었습니다.

 

크게 보자면 5개의 단계를 거칩니다.

1. 문서 만들기
2. Github Repository 만들기
3. 빌드 세팅 설정
4. 문서 export
5. Github Pages 설정

 

문서는 앞선 글들을 통해 만들었고, Github Repository를 만들고 로컬과 연결하는 것도 크게 어렵지 않기 때문에 3단계부터 시작하겠습니다.

 

Repository이름을 Swift-DocC-Example로 해서 만들었습니다.

 

빌드 세팅 설정

 

문서가 빌드되는 Hosting Base Path를 설정해주기만 하면 됩니다.

 

 

Project  ->  Build Setting  ->  `documentation compiler - Options`  ->  DocC Archive Hosting Base Path에 Repository 이름을 설정해주면 됩니다. 간단하죠?

 

 

 

 

문서 Export

빌드 설정이 끝났다면 문서를 빌드해줍니다. Build Documentation (단축키 Ctrl + Cmd + Shift + D)

 

 

Export

 

빌드가 완료되면 문서 뜨게되는데, 왼쪽 네비게이션바에서 문서를 오른쪽 클릭해주고 Export 해줍니다.

 

docs

 

디렉토리 이름은 docs로 합니다. 다른 이름도 상관은 없겠지만 애플의 컨벤션이 docs인 걸로 보이니 그냥 맘 편하게 docs로 했습니다. (저는 이미 Export를 했기때문에 docs 디렉토리가 존재하고 있습니다)

 

Push 완료

 

커밋 - 푸시를 해줍니다.

 

 

 

Github Pages 설정

이제 Github Pages를 설정만 해주면 됩니다. Repository - Setting - Pages로 들어갑니다.

 

 

 

아무 설정도 안 한 상태입니다. 여기서 Branch 설정을 main - docs로 하고 save 버튼을 눌러줍니다.

 

main - docs

 

Pages가 정상적으로 배포 되면 아래와 같이 링크가 나타납니다. (이 과정에 시간이 몇 분 소요될 수 있습니다)

 

 

Visit Site 눌러서 방문해보면

 

 

엥? 

 

 

이상한 오류 메시지를 볼 수 있는데 걱정마세요. 아직 정확한 URL를 입력 안 했습니다!

 

 

 

문서 URL

문서를 배포하게 되면 애플이 만들어 놓은 기본 URL로 배포가 됩니다.

 

기본 문서 - https://username.github.io/repository-name/documentation/swift-DocC-name/

튜토리얼 - https://username.github.io/repository-name/tutorials/swift-DocC-tutorial-name/

 

빨간색에 해당하는 걸 작성해주면 됩니다.

 

제 github username은 never-better

현재 문서 프로젝트의 repository-name은 Swift-DocC-Example

swift-DocC-name은 Electronics_View입니다. 여기서 주의할 것이 swift-DocC-name은 소문자로 작성해야합니다!

swift-DocC-tutorial-name은 electronicsview 입니다.

 

 

제 공식문서 주소는 https://never-better.github.io/Swift-DocC-Example/documentation/electronics_view/ 가 됩니다.

튜토리얼 주소는 https://never-better.github.io/Swift-DocC-Example/tutorials/electronicsview/  입니다.

 

swift-DocC-name이 헷갈 수 있는데 쉽게 찾는 법을 알려드리겠습니다.

 

Github Repository에 들어가서 docs - documentation으로 들어갑니다.

 

Repository - docs - documentation

 

그러면 2개의 디렉토리가 있습니다.

 

그 중 하위 디렉토리가 없는 디렉토리가 swift-DocC-name 입니다. 예제에서는 electronics_view가 됩니다.

 

 

더 확실한 방법은 디렉토리를 직접 확인해보면 됩니다. 공식 문서 디렉토리의 경우 index.html과 함께 다른 문서들이 들어있는 디렉토리가 있습니다.

 

swift-DocC - name 에 해당하는 디렉토리

 

 

다른 디렉토리의 경우 index.html 파일만 있습니다.

 

index.html만 있음

 

 

튜토리얼도 마찬가지로 디렉토리를 직접 확인해보면 됩니다.

 

tutorials/electronicsview

 

 

배포된 공식문서를 확인해보겠습니다.

 

Documentation

 

 

 

 

애플 공식문서st로 제 프로젝트 문서가 만들어졌네요!

 

 

 

배포된 튜토리얼도 확인해보겠습니다.

 

 

Documentation

 

 

 

아주 잘 만들어졌네요!

 

 

 

정리

이렇게 해서 DocC로 만든 문서 배포까지 완료했습니다. 설정 몇 개만 해주면 되서 어렵지 않았던 것 같습니다.

 

 

시리즈를 통해 Swift DocC의 기본 개념에 대해 알아보고, 예제 프로젝트를 통해 공식 문서 Reference, Article, Tutorals를 만들어 배포까지 완료했습니다. 앞으로 DocC를 통해 더 깔끔한 프로젝트 공식 문서를 만들어야겠습니다. 😁

 

 

코드와 문서는 Github 에서 확인할 수 있습니다.

 

GitHub - never-better/Swift-DocC-Example: Swift DocC 예제

 

Swift DocC 문서 만들기 시리즈 끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝끝

 

 

 

 

출처

What's new in Swift-DocC - WWDC22 - Videos - Apple Developer