sphinx 파이썬 문서 github pages 배포

jekyll rtd theme

sphinx는 문서를 빠르고 간단하게 만들 수 있게 도와주는 툴인데요.

종종 위 사진처럼 파이썬 documentation이 구성되어있는 것을 볼 수 있습니다.

본 포스팅에서는 jekyll rtd theme를 적용해서 깃헙레포에 배포하는것까지 진행해보도록 하겠습니다

 

자신의 만든 라이브러리나 프로그램의 사용법에 대한 소개 페이지를 만들고 싶다면 이 포스팅을 통해 알아가보도록 합시다.

 

패키지 설치

sphinx는 파이썬으로 작성되었으므로 파이썬 패키지를 설치해주어야 합니다.

pip install Sphinx, sphinx_rtd_theme

 

깃헙 레포 생성 및 클론

GitHub - ghdic/sphinx: sphinx테마 테스트

깃헙에 레포를 생성하고 클론하여 작업할 준비를 해줍시다.

레포 생성정도는 다 할줄안다고 생각하고 넘어가겠습니다...

 

환경은 윈도우이며, IDE는 파이참을 사용했다는점 참고해주세요.

 

sphinx 초기 설정

먼저 문서 배포 관련 파일을 한곳에 모아두기 위해 docs라는 폴더를 생성한 후 거기서 작업해줄것입니다.

터미널 경로는 프로젝트 최상단 위치를 기준으로 시작합니다.

mkdir docs
cd docs

이제 sphinx관련 초기설정을 진행합니다

해당 명령어가 아나콘다 환경의 경우 제대로 진행되지 않는 경우가 있습니다

해당 라이브러리가 설치된 Script폴더에 환경변수 설정을 해주시거나 절대경로를 다 써주시면 되겠습니다

sphinx-quickstart

초기 설정

각문항에 나는 위와같이 작성하였다.

본인의 상황에 맞게 작성해주면 된다.

 

첫번째 문항은 빌드&소스 디렉토리를 따로 분리하여 관리할것인지

두번째는 프로젝트명

세번째는 프로젝트 관리자명

네번째는 프로젝트버전

다섯번째는 프로젝트 언어이다.

 

해당 입력이 다 끝났으면 docs폴더 안에 여러파일이 생성된걸 볼 수 있다.

이제 생성된 파일중 conf.py 파일을 통해 작업해보자 

 

sphinx rtd theme적용

Sphinx Themes Gallery

위 사이트에 들어가면 rtd theme 이외에도 여러 테마가 존재한다

필자는 이 테마가 제일 맘에 들기때문에 이거로 진행하도록 하겠다

Installation — Read the Docs Sphinx Theme 1.0.0 documentation

좀 더 자세한 설정을 하고 싶다면 docs를 참고하자

 

빨간줄 친 부분을 따라 변경

위와 같이 변경만 해주면 rtd theme적용이 끝난것이다. 정말 간단하다!

 

github에 배포하기

이제까지 잘 따라왔다면 이제 페이지를 빌드해보자

make html

 

docs 폴더 위치에서 명령어를 수행해야 한다

다음과같이 에러 없이 빌드가 되었다면 성공한것이다.

build폴더에 index.html 폴더를 눌러 결과물을 볼 수 있다.

깃헙에 배포하기전에 매번 make html을 해야 할필요는 없다.

git Action에서 자동으로 빌드 후 배포하기 때문이다.

그래도 작성한 파일에 에러가 있는지 확인 할 수 있으니 배포전 한번만 해주자

올리지 않아도 되는 build폴더 gitignore로 제외해주자

루트폴더에 .gitignore파일을 다음과 같이 만들어준다

 

.gitignore

docs/_build/

깃헙 페이지에 배포

해당 결과물들을 커밋하고나서 페이지 배포를 진행해보자

설정에 들어가서 docs폴더 기준으로 페이지가 배포될 수 있도록한다

git Action에서 배포가 정상적으로 이루어졌는지 확인 할 수 있다

하지만 여기까지 진행해도 해당 페이지에 들어가면 404가 뜰것이다.

분명 처음 위와같이 진행했을때 배포가 잘됐었는데... 어캐했는지는 아직도 미스터리이다.

깃헙에 페이지가 배포되기 위해서 빌드 진행하고 빌드한 결과물을 레포지토리에 올려야된다

이와 같은 진행을 git action을 통해 자동화 할 수 있다.

 

git action을 통한 github page 빌드 및 배포

Appendix: Deploying a Sphinx project online — Sphinx documentation

이부분에서 가장 많이 삽질을 했었던것 같다.

document에서 하란대로 했는데 안되서 오류고치고 이것저것 만지면서 해결했다 ㅠ

시행착오를 한 순으로 어떻게 해결했는지에 대해 작성해보겠다.

git action을 작동 시키기 위해 다음과 같은 경로에 해당 파일을 만들어주자

 

.github/workflows/sphinx.yml

name: Sphinx build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Build HTML
      uses: ammaraskar/sphinx-action@0.4
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

이제 커밋을 해보고 action탭에서 결과를 확인해보자

 

sphinx-log를 찾을수 없다는 에러가 뜬다

해당 에러를 없애기 위해서 솔루션을 찾아보았다.

Action fails with due to missing log file · Issue #5 · ammaraskar/sphinx-action

Makefile에서 "SPHINXOPTS ?=" 이라고 써져있는 부분을

"SPHINXOPTS +=" 이라고 수정 해주라고 한다 

 

docs/Makefile

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    +=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

다시 커밋을 해보자

 

이번에는 다른오류가 난다. 우리가 사용하는 모듈이 안깔려 있어서 나는 오류이다

해당 오류를 해결하기 위해서는 우리가 사용하는 라이브러리들을 requirements.txt로 적어주면 된다.

본인 프로젝트에서 사용하는 라이브러리가 더 있다면 추가적으로 아래와 같이 적어주자

별다른 설정없이 따라하고 있다면 그대로 적어주면 된다.

 

docs/requirements.txt

sphinx_rtd_theme==1.0.0
myst-parser==0.18.0

여기까지하고 커밋을 했다면 이제 git action에서는 문제 없이 다 성공한다

그런데 gh-pages브런치에 들어가면 다음과 같이 나온다

????

우리가 빌드한 결과물이 배포가 되지 않고 있다... 왜인지 알아보니 다음과 같았다.

 

위에서 작성했던 git action sphinx.yml 소스는 documentation에 올라와있는것이다

여기서 살짝 고쳐야할것이 있는데

우리의 폴더구조를 보면

_build라고 되어있는것을 볼 수 있다. 하지만 위에 path을 보면 build라고 되어있기 때문에 경로가 맞지 않아 이부분을 고쳐 줘야한다.

나는 publish_dir도 _build로 고쳐주었다

 

.github/workflows/sphinx.yml

name: Sphinx build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Build HTML
      uses: ammaraskar/sphinx-action@0.4
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: html-docs
        path: docs/_build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/_build/html

여기까지 진행하고 커밋을 진행하고 git actions를 보면

정상적으로 git action작동

gh-pages브랜치에 정상적으로 빌드결과가 배포됌

해당 사항이 다 확인되었다면 마지막으로 기존에 세팅했던 page source 경로를 다시 바꾸어주자

페이지 설정이 끝나면 git action이 다시 진행된다. 해당 action이 끝난걸 확인하고 들어가보자!

다음과 같이 정상적으로 배포된걸 확인 할 수 있다.

환영합니다 — sphinx 1.0 문서

 

markdown 적용

docs 폴더안을 잘보면 index.rst라는 파일이 있다.

이 파일이 우리 문서에 루트 파일이 되어줄 파일이다.

그런데 확장자가 우리한테 친숙하지 않다.
대부분 깃헙 사용자라면 마크다운이 익숙할테니 말이다.

Markdown — Sphinx documentation

라이브러리 설치해주고

pip install myst-parser

 

다음과 같이 conf.py파일을 고쳐주자

빨간 네모친곳을 따라 변경

각각의 확장자에 따라 어떤 방식으로 해석할것인지를 정의하는 것이다.

다만 여기서 .txt확장자를 markdown으로 지정해버리면 requirements.txt에 toctree가 지정되어있지않다고 warning이 뜰것이다. 해당 메세지가 거슬리면 그냥 txt확장자를 포함 안해도 된다.

이제 파일명.md라고 만들면 해당 파일을 html파일로 빌드하여 배포 할 수 있을 것이다.

 

만약 rst그대로 쓰고 싶다면 아래 튜토리얼을 보고 문법을 익혀서 써보자

Sphinx Tutorial — Sphinx Tutorial 1.0 documentation

 

docs폴더를 기준으로 md, rst, txt 확장자로 파일을 만들어 포스트하고 싶은 글을 적어서

자유롭게 작성해보자. 목차를 작성하느데 쓰는 toctree같은 애네만의 문법도 있는데 이건 사용하면서 숙지하면된다.

아래에 도큐먼트 글을 보고  잘 숙지해보자

Directives — Sphinx documentation

 

docs 사이트에 배포하기

깃헙으로 배포하는법도 있지만, Read the Docs라는 곳에서도 우리가 만든 레포를 배포할 수 있게 해준다

홈 | Read the Docs

사용법은 간단해서 깊게설명하지 않겠다

그냥 깃헙으로 회원가입해서 만든 레포를 눌러서 배포하면 깃헙 페이지에서 배포되는것처럼 배포된다

yaml파일로 세부설정도 가능한것 같다.

아래는 내가 테스트로 올려본것이다.

Welcome to marinelife’s documentation! — marinelife 1.0 documentation

 

지금까지 sphinx를 생성하여 빌드하고 배포하는것까지 해보았다.

구현한 함수에 대해 자동으로 문서화 하는 기능도 있다고 하고,

sphinx, rst 관련 문법도 다루면 좋겠지만 너무 힘들어서 여기까지 하는거로~