[Python] 파이썬으로 개발 문서를 만들어보자! Sphinx!

개발 문서를 제대로 만들어본 적은 없지만 실력이 있는 개발자가 되기 위해서는 API나 개발 문서를 잘 작성해야 한다는 생각이 든다.

 

그러다 Python의 Sphinx를 이용하면 개발 문서를 쉽고 예쁘게 작성할 수 있다는 글을 보게 되었다.

 

 

Python documentation의 하단에도 'Created using Sphinx 2.4.4.'라는 문구가 적혀 있었다.

 

Sphinx 사용해보기

 

pip install Sphinx

 

우선 Sphinx를 사용하기 위해서는 pip을 사용하여 Sphinx를 설치해야 한다.

 

설치가 끝났다면

 

sphinx-quickstart

 

를 사용해 개발 문서를 만들면 된다.

 

한글로 설명이 뜨는게 뭔가 신기하다.

 

선택한 루트 경로는 .으로 바로 설정이 되고 다음으로 두 가지 옵션 중 선택하라고 안내가 뜬다.

y를 입력할 경우 루트 경로 내에서 "source"와 "build" 디렉터리가 분리가 된다.

 

n을 입력할 경우 루트 경로에 "source" 폴더 안에 있던 파일들이 들어가고 "_build" 폴더 안에 build가 되게 된다.

 

 

취향 차이겠지만 분리를 하는 게 훨씬 깔끔하게 보이는 것 같다.

 

 

다음으로는 프로젝트 이름, 작성자 이름, 프로젝트 릴리스를 차례로 묻는다.

 

 

다음은 문서의 언어를 물어본다.

기본값은 en이기 때문에 영어로 작성할 사람은 엔터를 입력하면 되고 한글로 작성할 경우 ko, 혹시라도 일본어로 작성할 사람이 있을 경우에는 ja를 입력하면 된다.

 

 

프로젝트 언어를 입력하고 나면 이렇게 초기 디렉토리 구조가 생성되었다는 문구가 출력이 되면서 완료가 된다.

 

make html

 

make html을 입력하게 되면 해당 문서가 html 구조로 만들어진다.

 

 

테마 변경하기

 

"source" 폴더 밑에 있는 conf.py에 각종 설정이 적혀 있고 index.rst에 위에 보이는 index.html을 만드는 기본 틀이 작성되어 있다.

 

테마가 마음에 들지 않을 경우

 

https://sphinx-themes.org/#themes

Sphinx Themes Gallery

 

위 사이트에서 테마를 선택하여 conf.py의 html_theme에 적어주면 된다.

 

 

나는 Book 테마가 마음에 들어 Book 테마를 적용해보기로 하였다.

html_theme에 테마명을 적어주기 전에 테마도 pip을 이용하여 다운로드해야 한다.

자세한 설명은 각 테마를 눌러보면 나오는 데모 페이지에 적용 방법이 적혀 있다.

 

pip install sphinx-book-theme

 

pip을 이용하여 테마를 받아준 다음

 

 

conf.py의 html_theme에 테마명을 적어준 다음 make html을 다시 한번 해보면 테마가 적용이 된다.

 

 

마크다운(Markdown) 사용하기

 

Sphinx는 reStructuredText라는 .rst 파일로 작성이 된다.

하지만 마크다운을 사용하여 작성할 수도 있기 때문에 익숙한 마크다운을 사용할 수 있도록 설정해 준다.

 

우선 마크다운을 사용하기 위한 CommonMarkParser라는 라이브러리를 설치해야 한다.

 

pip install recommonmark

 

pip을 사용하여 설치한 뒤 conf.py의 몇 가지를 수정하면 된다.

 

# 아래 세 줄은 기존에 주석 처리 되어있어
# 주석을 해제하면 된다.
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

from recommonmark.parser import CommonMarkParser

source_parsers = {
  '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

extensions = ['recommonmark']

 

 

 

위와 같은 마크다운 파일을 작성하여 테스트해보았다.

 

 

index.rst의 .. toctree:: 부분에 경로를 적어주면 메인 화면에 좌측과 메인에 tree 구조로 나타나게 된다.

 

 

메인과 좌측 메뉴에 제대로 마크다운이 읽어와 작성이 되었다.

 

 

하지만 내용을 확인해보니 테이블이 제대로 표시가 되지 않았다.

 

해결하기 위해 sphinx-markdown-tables 확장을 적용하기로 하였다.

 

pip install sphinx-markdown-tables

 

우선 pip을 사용하여 sphinx-markdown-tables를 설치해 준다.

 

 

그다음 conf.py의 extensions에 'sphinx_markdown_tables'를 추가해 준다.

그 뒤 make html을 다시 실행해 보면

 

 

테이블이 제대로 표시되는 것을 확인할 수 있었다.

 

 

웬만한 마크다운이 제대로 표시되는 것도 확인하였다.

 

 

 

 

대충 Sphinx를 사용하는 방법에 대해 알아보았는데 아직까지는 어떻게 활용해야 할지 감이 잘 안 온다.

공부하다 보면 개발 문서의 중요성도 더 알게 되고, 작성하다 보면 요령이 생길 테니 계속해서 공부해야겠다.