readthedocs.org에 문서화하는 방법

1. readthedocs.org 가입

readthedocs.org

위 사이트로 들어가서 회원가입을 진행한다.

2. Sphinx 설치

먼저 문서화할 파이썬 소스 폴더로 들어가서 docs라는 폴더를 하나 생성한다. 

pip3 install sphinx

그리고 위 명령어를 통해 sphinx를 설치한다. 그리고 아래의 명령어를 통해 설정을 시작한다.

sphinx-quickstart

대충 뭐 이런식으로 여러가지 질문들이 나오는데 원하는대로 설정을 해주면,

최종적으로 위와 같은 화면을 볼 수 있다.

make html

마지막으로 위 명령어를 내려주면 설정을 토대로 파일들이 생성된다.

3. 테마 설정

pip3 install sphinx-rtd-theme

위 명령어를 통해 테마를 설치한다. 기본적으로 설치되는 테마는 조금 직관적이지가 않아서 교체해주기 위함이다. 설치한 후 docs/conf.py 파일을 열고 최상단에 

import sphinx_rtd_theme

를 적어준다.

그리고 중간에 있는 extensions 배열에 sphinx_rtd_theme을 추가한다.

그리고 html_theme도 sphinx_rtd_theme 로 바꿔준다. 마지막으로 파일 최하단에

master_doc = 'index'

를 추가해주면 테마 적용이 완료된다.

4. Repository 임포트

가입 후 로그인을 하면 오른쪽 상단에 자신의 계정 이름이 표시된다. 해당 이름을 클릭하고 My Projects 버튼을 누르면 프로젝트를 Import할 수 있는 공간이 존재한다.

+ 버튼을 눌러서 원하는 레포지터리를 임포트시킨다.

설정이 맞는지 확인한 후 Next 버튼을 누른다.

Build version 버튼을 눌러서 빌드를 시작한다.

위와 같은 화면이 나온다면 정상적으로 빌드가 완료된 것이다. 이제 위쪽에 있는 View Docs 버튼을 눌러보면

위처럼 테마가 적용되어 배포된 모습을 확인할 수 있다.