Python 패키지 개발일지 07: 스핑크스 개인화

스핑크스(Sphinx)를 사용해 본격적으로 문서를 만들기 전에 만들어둔 깃허브(GitHub) 저장소와 스핑크스를 연동하는 작업을 하도록 하겠습니다. 이 작업은 반복 입력을 효과적으로 줄여줍니다.

관련 글

• Python 패키지 개발일지 02: 깃허브에 패키지 올리기
• Python 패키지 개발일지 03: PyPI에 패키지 올리기
• Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화

readme.md 연결

index.rst와 readme.md를 연결하기 위해 m2r 패키지를 사용합니다.
명령창에 pip install m2r(아나콘다의 경우 conda install -c conda-forge m2r)를 입력하여 m2r을 설치한 후, conf.py를 열어 아래 내용으로 수정합니다.

extensions = [
    "m2r"
]
source_suffix = ['.rst', '.md']

최신 버전의 스핑크스를 사용해 초기화한 경우 extensions 항목은 있지만, source_suffix 항목은 새로 만들어야 합니다. readme.md의 내용을 사용자 문서의 첫 화면에 연동하기 위해 index.rst를 열어 원하는 위치에 다음을 추가합니다.

.. mdinclude:: ../readme.md

이 줄을 추가한 지점에 깃허브 저장소의 readme.md를 추가합니다.

.. mdinclude:: ../readme.md
  :start-line: 17
  :end-line: -2

이렇게 추가옵션을 줄 수도 있습니다. :start-line:은 가져오기 시작하는 줄을 나타내고, :end-line: 어디까지 가져올지를 정합니다. 숫자는 양수와 음수를 모두 사용할 수 있으며, 음수의 경우에는 문서의 끝에서부터 줄 수를 셉니다.

버전 연동

• Python 패키지 개발일지 03: PyPI에 패키지 올리기

앞선 글에서 setup.py와 패키지의 __init__.py의 버전 정보를__version__에 담아 my_package.__version__으로 연동했습니다. 이번에는 패키지의 버전 정보를 config.py와 연결합니다.

import os
import sys
sys.path.insert(0, os.path.abspath('..'))
import my_package

# The full version, including alpha/beta/rc tags
release = my_package.__version__

HTML 출력 위치 변경

깃허브 페이지(GitHub Pages)는 저장소의 일부나 저장소 전체를 정적 HTML 웹페이지로 보여줍니다. 저장소 > Setting 탭 > GitHub Pages항목에는 깃허브 페이지를 위한 설정이 있습니다. Source 항목을 변경하여 프로젝트 루트의 docs 디렉토리를 깃허브 페이지를 위한 정적 웹페이지로 설정합니다.

make.bat을 열어 set BUILDDIR=build를 set BUILDDIR=docs로 변경합니다. 이대로 깃허브에 푸시하면 페이지가 정상적으로 나오지 않는데요. 이것은 빌드한 문서의 URL 위치가 {user}.github.io/{my_package}/가 아닌 {user}.github.io/{my_package}/html/이기 때문입니다. docs/가 아닌 docs/html/에 출력한 것인데요. 매번 상위 디렉토리로 옮기는 것도 좋지만, 귀찮다면 docs/에 index.html을 만들어 아래 내용을 채워넣고 푸시하면 됩니다.

<meta http-equiv="refresh" content="0; url=./html/" />

이제 docs/index.html의 도움으로 {user}.github.io/{my_package}/로 접속했을 때 자동으로 사용자를 {user}.github.io/{my_package}/html로 넘겨줍니다.

깃허브 제외파일 변경

.gitignore에 다음 내용을 추가해서 빌드 중 생기는 파일들을 제외하고, 공통 파일도 제외합니다.

# Sphinx
build/
doctrees/
Makefile
make.bat

이 중 Makefile은 윈도우 OS 환경에서는 사용하지 않으니 삭제해도 무방합니다.