DocC

DocC

목차

DocC 에 대한 결론
DocC 사용 방법
1. DocC 작성방법
2. Documentation Catalog 생성
3. Build Documentation
4. Github Pages 에서 원하는 브랜치에서 호스팅

DocC 에 대한 결론

• 사용해야 할지 잘 모르겠습니다. Wiki 를 적극적으로 활용하게 된다면 DocC 의 대체가 되지 않을까 생각합니다.
• 만들어지는 파일이 너무많고, 매번 Document 를 Export 해주어야 한다는 불편함, Markdown 언어를 지원하지만 편리한 편집이 용이하지 않다는 점으로 미루어 보아 기술 스택에 관련된 것은 Notion Page 나 GitBook, README, Wiki 등을 대신 사용하는 것이 어떨까 하는 개인적인 생각이 있습니다.
• 주석은 DocC 를 기반으로 하고, Publish 는 나중에 최종적으로 Export 하여 관리하는 것도 좋을 것 같다는 생각이 들었습니다. Github 과 연동하게 된다면 Export 하고 Push 하게 된다면 웹사이트에 자동 적용이 되기 때문에 크게 불편하지는 않은 것 같습니다.

장점

• Quick Help 로 해당 함수나 변수에 대한 주석을 빠르게 확인 가능하다. (가장 강력한 기능인듯)
• 정돈된 멋진 Documentation 을 생성 할 수 있다. (개발자스럽다(?))

단점

• 파일이 많이 길어진다.
• 주석을 작성하는데도 품이 든다.
• 만들어진 Documentation 을 내 입맛대로 Publish 하는게 어렵다.
• 매번 Documentation 을 Export 해주어야 한다.

DocC 사용 방법

DocC 작성방법

• 작성한 코드 (함수, 변수 등) 위에 /// 로 주석을 달게 되면 아래 스크린샷과 같이 Quick Help 에서도 볼 수 있는 편리한 주석이 생깁니다.

• 주석을 달 곳의 이름위에 커서를 놓고 option + command + / 단축키를 사용하게 되면 아래와 같이 정돈된 주석을 달수도 있습니다.

• option + command + / 단축키 사용 예시

Documentation Catalog 생성

• 아래 스크린샷과 같이 Documentation Catalog 를 생성해줍니다.

• 아래와 같은 Documentation 파일이 생성된 것을 확인할 수 있습니다.
  • @Metadata { @PageColor(orange) } 처럼 페이지 제목 색상도 정해줄 수 있습니다.
  • 이 이외에도 설정 할 수 있는 것들이 많은 것 같습니다.

Build Documentation

• 상단의 Product 메뉴에서 Build Documentation 혹은 shift + control + command + D 단축키로 Documentation 을 Build 합니다.

• Documentation 이 만들어 졌군요!

• Documentation 을 Export 합니다.
  • Documentation 에서 ... 부분을 눌러 Export 해주는데 이때 프로젝트 파일의 최상위 폴더에 docs 라는 이름으로 Export 해 줍시다.
  • 여기서 파일이 2000개가 넘게 생성이 됩니다...

Github Pages 에서 원하는 브랜치에서 호스팅

• Branch 는 tyler, 그리고 docs 파일을 대상으로 합니다.

• 1~2분이 지나면 위와같이 Visit site 가 생기게 됩니다.

• https://bostongosari.github.io/Baseline/ 이 아닌 https://bostongosari.github.io/Baseline/documentation/tyler 로 들어가면 아래 처럼 생긴 Docs 를 확인할 수 있습니다. 링크
  • 색상을 orange 로 만들었는데 아주 별로인 색상이 나왔네요...