[CI/CD] (초보자도 바로 하는) Sphinx 문서 Github 자동 배포

1. Sphinx Documentation 이란?

Sphinx Documentation 은 파이썬 주석을 기반하여 자동으로 문서화를 해주는 오픈소스이다.

아래는 Sphinx Dcoumentation 공식 사이트이다.

Sphinx makes it easy to create intelligent and beautiful documentation.

https://www.sphinx-doc.org/en/master/

Welcome — Sphinx documentation

문서화?

소프트웨어를 개발하고 유지보수를 진행하다 보면 문서화가 중요해진다.

코드 내 버그를 수정하거나 추가 개발을 할 때마다 문서를 작성하고 남기는데, 개발자 입장에서는 여간 귀찮은게 아니다.

 

기본의 소양을 갖춘 개발자들은(...) 모듈의 기능, 모듈 안의 function의 역할 등을 주석으로 남겨놓는데,

이를 하나로 모아 자동으로 html 형식의 웹 문서화를 해주는 것이 바로 Sphinx documentation 이다.

 

* 참고로 python 공식 문서 또한 이 sphinx documentation을 사용하여 만들어졌다. ("Created using Sphinx 4.5.0")

https://docs.python.org/3/

2. Sphinx Documentation 작성

python3 이 설치되어 있다고 가정하고 이제 같이 sphinx documentation을 만들어 보자.

2-1. Sphinx 설치

python3 -m venv .venv
source .venv/bin/activate

pip3 install sphinx

pip install sphinx

2-2. Sphinx quickstart

docs라는 폴더를 만들어주고, sphinx-quickstart docs 명령어를 실행하면 여러 설정에 관하여 프롬트가 뜬다.

mkdir docs
sphinx-quickstart docs  # n

sphinx-quickstart docs

 

설정이 끝났으면 한번 빌드를 해보자.

cd docs
make html
open _build/html/index.html

index.html

Sphinx index.html

성공적으로 나온다! 이제 조금 더 이쁘게 바꾸어 보자.

2-3.  Sphinx deep-dive

2-3-0.  문서화 시킬 모듈 구조

간단한 calculator (계산기) 모듈이다. 다양한 테스트를 위해 calculator.py 안에 calculator 클래스를 만들고, calc_numbers에 main 함수를 넣고 모두 docstring을 작성하였다.

├── LICENSE
├── README.md
├── docs
│   ├── Makefile
│   ├── _static
│   ├── _templates
│   ├── api
│   ├── conf.py
│   ├── index.md
│   ├── make.bat
│   ├── markdown
│   └── requirements.txt
├── pyproject.toml
├── requirements.txt
└── src
    ├── __init__.py
    ├── calc_numbers
    │   ├── __init__.py
    │   ├── calc_numbers.py
    │   ├── calculator.py
    │   └── nums.jpeg
    └── custom_logger
        ├── __init__.py
        └── custom_logger.py

2-3-1.  configuration 파일: conf.py

docs/conf.py

import sys
sys.path.insert(0, os.path.abspath(".."))

sys.path 에 상위 경로를 추가하여 docs 폴더 바깥에 위치한 src란 폴더를 인식할 수 있게 하였다.

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx.ext.todo",
    "sphinx.ext.githubpages",
    "sphinx.ext.viewcode",
    "sphinx.ext.autosummary",
    "sphinx_autodoc_typehints",
    'sphinxcontrib.mermaid',
    'myst_parser'
]
exclude_patterns = [".venv", "_build", "Thumbs.db", "*.egg-info", ".DS_Store", "**.ipynb_checkpoints"]

그리고 외부 extensions 들과 sphinx build 할 시 제외 되어야 하는 파일 형식을 지정해 주었다.

(마치 .gitignore 느낌으로)

전체 파일은 아래 링크를 참고하자.

https://github.com/ampersandor/calculator/blob/main/docs/conf.py

2-3-2. autosummary (index.rst)

docs/api/index.rst

sphinx의 핵심!이라 불릴 수 있는 autosummary 기능이다. 명시한 폴더 내 모든 docstring을 가지고 자동 문서화를 해준다.

나는 그저 src 내 모든 파일을 읽어오라 하였다.

보통 index.rst는 docs/index.rst에 있지만, 2-3-3에 나올 마크다운과 구별하기 위해 docs/api/index.rst 에 위치시켰다.

.. calculator documentation master file, created by
   sphinx-quickstart on Tue Nov  7 12:56:03 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to calculator's documentation!
======================================

.. autosummary::
   :caption: API
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   src

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

2-3-3.  markdown section

docs/markdown/

마음대로 작성할 수 있는 markdown 폴더를 만들었다. 사실 이건 안해도 된다.

2-3-4. index.md (with mermaid)

docs/index.md

앞서 만든 2-3-2 와 2-3-3 을 indexing 해주는 코어 index.md이다. 아름답게도 mermaid 도 그려보았다.

---
myst:
  html_meta:
    "description lang=en": |
      Top-level documentation for pydata-sphinx theme, with links to the rest
      of the site..
html_theme.sidebar_secondary.remove: true
---

# Calculator
```{mermaid}
flowchart TB
    add:::id1 ==> minus:::id1
    classDef id1 fill:#f9f,stroke:#333,stroke-width:4px
```
```{seealso}
This is seealso
```
## Documents
The content of the `Calculator` API.
```{toctree}
:maxdepth: 1
markdown/index
```
## API
The content of the `Calculator` API.
```{toctree}
:maxdepth: 2
api/index
```

 

2-3-5.  requirements.txt

pydata-sphinx-theme이라는 외부 테마와, mermaid 등 앞서 언급한 기능을 사용하기 위해 pip3 install -r 명령어로 설치해야한다.

sphinx_autodoc_typehints
sphinx_rtd_theme
sphinx-book-theme
pydata-sphinx-theme
recommonmark
sphinxcontrib-mermaid
myst-parser
sphinx==6.2.1

2-3-6. Makefile

주석을 보면 그림 데이터도 있다, 이를 위해선 src/ 안에 있는 모든 사진 파일들을 _autosummary 폴더에 넣어주어야 하는데, 매번 찾기 귀찮으니까 자동으로 찾아오게 하였다.

...

clean: # ampersandor
	rm -rf ./_autosummary
	rm -rf ./_build
prepare: # ampersandor
	mkdir -p api/_autosummary
	find ../src -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" \) -exec cp '{}' ./api/_autosummary/ \;    
...

%: clean prepare Makefile # ampersandor
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

2-3-7. _static

docs/_static

style.css, 그리고 favicon.ico 같은 자잘한 리소스를 넣어두자. 아름다움을 위해서는 귀찮음을 감수해야한다.

2-3-8.  _templates

docs/_templates

autosummary에서 어떻게 모듈에 있는 docstring을 쓸지 rst형식의 틀이다.

 

2-3-9. 마지막

# 먼저 calculator 모듈을 빌드하고 설치한다. 이건 toml 파일 형식을 사용하여 패키지화를 미리 해두었다.
# calculator에서 실행
pip3 install --upgrade build
python3 -m build
pip3 install dist/calculator-0.0.1.tar.gz

# docs로 진입하여 실행
cd docs
pip3 install -r requirements.txt
make html

 

그럼 이런 화면이 나온다.

 

https://ampersandor.github.io/calculator/

Calculator — calculator 0.0.0 documentation

 

3. Github을 통한 자동 배포 (CD)

3-1.  github token 생성

https://github.com/settings/tokens

에 접속하여 token을 생성한다.

Personal access tokens 생성

아래와 같이 Expiration 기간과 scopes설정이 나올 것이다. 이때 workflows에 꼭 체크를 해주자.

(추가적으로 read:packages도 설정을 해주었다)

token 설정 화면

설정이 끝나 save 를 누르면 아래와 같은 화면이 나오는데, 아래 나오는 token을 꼭 복사해두자.

token 만들어진 화면

 

3-2. secret에 token 등록

그리고 repository 설정 탭에 들어가 방금 복사한 secret token으로 repository secret을 생성하자

3-3. git action 을 위한 workflow 작성

앞서 만든 secret key 를 활용하여 main branch 에 push 이벤트가 발생할 때 마다 git page가 자동으로 빌드되도록 할 것이다.

 

.gihub/workflows/sphinx.yml (위 폴더 경로는 똑같이 따라주어야 한다)

name: GitHub Pages
on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [ '3.10' ] # 3.10 으로 하면 3.1로 인식하기 때문에 quote를 해준다

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}

      - name: Build HTML
        run: |
          ./setup.sh
          cd docs
          pip3 install -r requirements.txt
          make html
          touch _build/html/.nojekyll

      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        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.my_secret }}
          publish_dir: docs/_build/html/

3-4. git push

sphinx.yml 파일 까지 만들었다면 repository에 올려보자

git add .
git commit -m "Initial commit"
git push origin main

 

Actions 텝을 가보면 아래와 같은 화면이 보일 것이다.

Git action 결과 로그 화면

3-4. git page 설정

repository의 Settings에 가서 Pages 섹션에 가서 아래와 같이 설정을 하자.

Custom domain을 구매한 사람이 있으면 설정을 할 수도 있다.

Github Pages 설정

3-5. edit repository details

좀더 쉽게 documentation page에 접근할 수 있도록 repository main 페이지 오른쪽 상단에 있는 설정에서 아래처럼

"Use your GitHub Pages websites" 를 체크해준다.

Edit repository details 화면

그리고 링크를 확인하면!

sphinx documentation example

 

 

어수선한 글 읽어주셔서 감사합니다~ 모두 좋은 하루 되세요~ 😁