본문으로 바로가기

readthedocs.org에 문서화하는 방법

category Coding/Python 2019. 11. 14. 19:06

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 버튼을 눌러보면



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



다른 사람들이 많이 읽은 글

댓글을 달아 주세요