2022. 8. 26. 12:44ㆍ카테고리 없음
나도 늘어나는 고객들의 기술지원을 하면서 반복된 질문들을 조금이나마 줄이고 또 우리 Product 에 대해 고객들에게 공개가능한 기술 문서를 제공하고자 매뉴얼 사이트를 구축하고자 했다. 이것저것 찾아봤지만 Readthedocs 가 가장 쓸만 하다고 판단했다. 그 이유는 다음과 같다.
- 전세계에서 가장 널리 쓰이는 검증된 서비스
- Markdown 문서 지원
- 엔지니어가 문서를 올리기 편해야 함
여기서 우리는 2번째 사실이 매우 중요했는데, 대부분의 고객지원 문서를 내부에서 Markdown 문서로 작성하고 있었기 때문이다. 만약 새로운 포맷으로 다시 매뉴얼을 작성해야 했다면 기술문서를 작성해야 하는 엔지니어들의 원망의 소리가 귓가에 맴돌아, 무조건 Markdown 문서를 지원해야 한다는 옵션을 최우선적으로 고려했다.
서론은 여기까지 하고 그럼 이제 실제로 간단한 Readthedocs 매뉴얼 사이트를 구축해보고 샘플 문서도 올려본다.
Read the Docs 계정만들기
다음 사이트에서 계정을 만들어주자. Read the Docs 는 Github 과 같은 저장소와 연동되어 매뉴얼 사이트를 빌드하기 때문에 가능하다면 본인의 Github 계정과 연동하여 계정을 생성하는게 좋다.
매뉴얼 관리용 Repository 만들기
Github의 Repository를 하나 만들어준다. 이 Repo 에는 실제 매뉴얼인 Markdown 문서 및 Read the Docs 설정파일들이 들어가게 된다. readthedocs-sample 이라는 이름의 Repo 를 만들어봤다.
Repository 에 설정파일 담기
Repository 폴더 구조는 다음과 같이 생성해준다.
readthedocs-sample
| +-- docs
| +-- index.md
| +-- sample.md
| +-- requirements.txt
| .readthedocs.yaml
| mkdocs.yml
- docs/requirements.txt : 마크다운 문서를 readthedocs 로 빌드할 때 필요한 패키지들 정보가 담겨있다. 해당 경로는 .readthedocs.yaml 에서 참조하고 있다.
- .readthedocs.yaml : Read the Docs 의 설정파일
- mkdocs.yml : mkdocs 의 설정파일
우리들이 담을 마크다운 문서 (index.md, sample.md 등)는 docs/ 디렉토리 아래에 담아주면 된다. docs/ 디렉토리 아래에 하위 디렉토리를 만들어도 알아서 잘 빌드해준다.
프로젝트 만들기
이제 다시 readthedocs.org 로 돌아와서 프로젝트를 생성해주자. 우측 상단의 계정 > 내 프로젝트에 들어가서 ‘Import a Proect’ 를 클릭해준다. Github 계정의 Repo 중의 연동할만한 Repo 목록이 뜬다. 방금 우리가 생성한 readthedocs-sample 의 + 버튼을 클릭해주자.
특별히 변경하고 싶은 내용이 없다면 변경하지 말고 ‘Edit advanced project options’ 만 체크하주고 다음을 클릭해주자. (참고로 기본 브랜치도 main 으로 그대로 놔두어도 된다. 나중에 알아서 main 브랜치가 생성된다)
그 다음 문서종류는 Mkdocs, 언어는 Korean 으로 선택한하고 Finish 를 눌러 마무리 해준다.
Repo에 Push 해서 반영되는지 확인해보기
Repo 에 파일들을 Push 하게 되면 자동으로 Read the Docs 상에서 빌드가 된다.
문서보기를 클릭하면 정상적으로 빌드되어 올라감을 확인할 수 있다. Read the Docs 에서는 빌드와 함께 사이트의 호스팅까지 제공해 준다. 보통 repository명.readthedocs.io URL로 호스팅이 제공된다. 유료로 돈을 내면 커스텀 도메인을 붙이거나, Private Repository 를 쓸 수 있는 등의 기능이 제공되나 보다.
mkdocs 개발서버를 띄워보기
하지만 mkdocs 를 빌드하기 전에 미리 마크다운 문서들이 미리 어떻게 보이는지를 확인하고 싶은 경우가 있을 것이다. 나도 그렇고…
그럴 경우 mkdocs 개발서버를 띄워서 미리 사이트의 느낌을 확인할 수 있다.
개발서버에 대한 자세한 내용은 이 매뉴얼을 참고하자.
Repository 가 있는 디렉토리로 이동하자. 아무래도 Python 패키지를 깔아야 하고 커멘드로 개발서버를 띄워야 하니 리눅스나 맥 환경이 적절할 것 같다.
- mkdocs 를 설치한다.
cd ~/readthedocs-sample
pip install mkdocs
- mkdocs 서버를 띄우기 위해 필요한 Python package 들을 설치하자.
pip install -r docs/requirements.txt
- mkdocs 를 실행해보자. 아래와 같이 뜨면 정상적으로 잘 뜬거다.
~/readthedocs-sample$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.03 seconds
INFO - [23:02:08] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [23:02:08] Serving on <http://127.0.0.1:8000/>
INFO - [23:02:10] Browser connected: <http://127.0.0.1:8000/>
- 브라우저를 통해 http://127.0.0.1:8000 으로 접속해본다. 잘 뜨는 것을 확인할 수 있다.
이렇게 Repo 에 Push 를 하기 전에 먼저 개발서버를 통해 원하는 느낌으로 문서들이 잘 올라갔는지, 렌더링은 잘 되었는지 확인한 후 올리면 좋을 것 같다.