Python 패키지 개발일지 08: 스핑크스 & 깃허브 페이지 (중급)

앞에서는 최소한의 설정으로 그럭저럭 깃허브 패키지 저장소와 스핑크스(Sphinx)를 연동하고 깃허브 페이지에 등록했습니다. 이번에는 배치파일 변경, 스핑크스의 깃허브 페이지 확장, 테마를 다룹니다.

관련글

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

make.bat 변경

기존 make.bat을 백업하고 새로운 파일을 만듭니다. 이 배치파일은 페이지를 만든 후 자동으로 ./docs/html/ 안에 들어있는 파일을 ./docs/로 옮겨줍니다.

@Echo Off
set SPHINXBUILD=sphinx-build
set SOURCEDIR=sphinx_source
set BUILDDIR=docs

%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
FOR /D %%I IN (./%BUILDDIR%/html/*) DO (
  IF NOT EXIST "%BUILDDIR%\%%I\" (
    mkdir "%BUILDDIR%\%%I"
  )
  FOR /D %%J IN (./%BUILDDIR%/html/%%I/*) DO (
    IF NOT EXIST "%BUILDDIR%\%%I\%%J\" (
      mkdir "%BUILDDIR%\%%I\%%J"
    )
    move /Y %BUILDDIR%\html\%%I\%%J\* %BUILDDIR%\%%I\%%J\ >nul
    rmdir .\%BUILDDIR%\html\%%I\%%J\
  )
  move /Y %BUILDDIR%\html\%%I\* %BUILDDIR%\%%I\ >nul
  rmdir .\%BUILDDIR%\html\%%I\
)
move /Y %BUILDDIR%\html\* %BUILDDIR%\ >nul
rmdir .\%BUILDDIR%\html\

make.bat

662 B

html 출력을 위한 배치파일이므로 출력속성이 고정되어 있습니다. SOURCEDIR은 다른 소스와 헷갈리지 않도록 sphinx_source로 변경하였습니다. 저장소의 상황에 따라 변경하시면 됩니다. 파일 변경 후, 아래와 같이 명령하면 됩니다.

{프로젝트 루트}> ./make

스핑크스 깃허브 페이지 확장

깃허브 페이지는 파일을 지킬(Jekyll) 시스템으로 인식하려 하기 때문에 보통의 정적페이지임을 알려주는 .nojekyll파일이 필요합니다. 또한 페이지의 위치를 파일 기반이 아닌 URl 기반으로 파악하기 위해 기본 URL 위치가 필요합니다. 이런 것들을 자동으로 처리해주는 스핑크스의 확장도구가 sphinx.ext.githubpages입니다.

conf.py

html_baseurl = 'https://{user}.github.io/{my_package}/'
extensions = [
    'sphinx.ext.githubpages',
]

깃허브 페이지 확장은 스핑크스가 기본적으로 탑재하고 있기 때문에 이렇게 간단한 방식으로 사용할 것이라고 알려준 후,필요한 세부설정을 별도의 변수로 지정해주면 됩니다.

테마 변경

여기서는 사용자 메뉴얼을 호스팅하는 Read the Docs의 테마를 적용하는 방법을 기준으로 합니다. 스핑크스가 제공하는 기본 테마중에서 선택하는 경우에는 간단하게 이름만 변경해주면 됩니다.

conf.py

# -- Options for HTML output ------------------------------------

# The theme to use for HTML and HTML Help pages.
# See the documentation for a list of builtin themes.
#
# html_theme = 'alabaster'
html_theme = 'classic'

"Read the Docs"등 외부 테마를 사용하는 경우에는 두 가지 방법이 있습니다. 해당하는 파이썬 패키지를 설치해서 불러오는 방법과 소스파일을 가져와서 붙여넣는 방법이 그것입니다. 여기서는 소스파일을 가져와 테마로 등록하는 법을 다룹니다.

Read the Docs의 깃허브 저장소에서 releases버튼을 눌러 가장 최신의 소스코드를 내려받습니다. 글을 작성하는 시점에는 0.4.3이었습니다. 압축을 해제하면 나오는 sphinx_rtd_theme 폴더를 아래 프로젝트 경로로 옮깁니다.

{프로젝트 루트}
    └─ sphinx_source/
        └─ _themes/
            └─ sphinx_rtd_theme/

설정을 변경합니다.

conf.py

# -- Options for HTML output ------------------------------------

# The theme to use for HTML and HTML Help pages.
# See the documentation for a list of builtin themes.
#
# html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]

Read the Docs 테마를 적용한 메뉴얼