[python] sphinx 란? (사용법)

Sphinx는 빠르고 쉽게 그리고 예쁘게 문서화를 만들기 위한 툴입니다. Sphinx 사용 없이 html 문서화를 만든다고 하면 공수가 들고 개발자라면 디자인도 더욱 신경쓸게 많아 집니다. 하지만 Sphinx를 사용하면 손쉽게 문서화를 할 수 있는 환경을 만들 수 있습니다.

최근에 유명 프레임워크나 api 문서들을 보게 되면 비슷한 디자인들이 많았는데 알고 봤더니 Sphinx를 사용한 문서들이었습니다. Sphinx를 사용하기 위한 설치 방법들을 설명 드리겠습니다. 아래 내용은 직접 설치하면서 기록한 내용이기에 혹시나 더 필요하신 라이브러리들이 있으시면 설치하시면 되겠습니다.

1. 파이썬 설치. (파이썬이 기본적으로 설치가 되어 있으셔야 됩니다.)

2. Sphinx 설치. (Sphinx를 설치 하고 sphinx_rtd_theme테마가 마음에 들어 해당 테마를 설치해줍니다.)

pip install Sphinx
pip install sphinx_rtd_theme

3. 문서화를 만들 프로젝트로 가서 퀵스타트 명령어를 실행 합니다.

sphinx-quickstart    //리눅스인 경우
C:\ProgramData\Anaconda3\Scripts\sphinx-quickstart.exe    //윈도인 경우 설치한 경로에 파일 실행

4. conf.py 파일을 열어 경로는 주석을 풀어주고 테마는 마음에 드는 테마를 명시 해줍니다. (현재 테마(sphinx_rtd_theme는 위에서 설치한 테마입니다.)

// 주석 해제
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))

// 마음에 드는 테마로 변경
html_theme = 'sphinx_rtd_theme'

5. make 명령어롤 통해서 html을 생성해줍니다.

make html
make.bat html

6. docs/_build/html/index.html 경로로 가면 html 문서가 생성된 것을 볼 수 있습니다.