다음은 VSCode + Quarto + uv + GitHub Actions 기반 Python 기술 문서 자동 배포 구축 설명이다.
개요
Visual Studio Code, Quarto, GitHub, uv를 활용하여
- Python 기술 문서 작성
- 실행 가능한 코드 포함 (Jupyter 기반)
- GitHub Actions로 자동 배포 (CI/CD)
환경을 구축한다.
1. 개발 환경 구축
1.1 필수 설치
확장 프로그램:
1.2 uv 설치
1.3 Quarto 설치 확인
2. Quarto 프로젝트 생성
1
2
3
| quarto create project book eda-for-python
cd eda-for-python
code .
|
3. uv 환경 구성
3.1 초기화
3.2 패키지 설치
1
| uv add numpy pandas matplotlib seaborn jupyter ipykernel
|
3.3 실행
4. 문서 작성
_quarto.yml:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| project:
type: book
book:
title: "EDA for Python"
author: "YK"
date: "2026. 3. 18."
chapters:
- index.qmd
format:
html:
theme:
- cosmo
- brand
execute:
freeze: auto
jupyter: python3
|
index.qmd:
1
2
3
4
5
6
7
8
| # 들어가기 {.unnumbered}
```{python}
import seaborn as sns
df = sns.load_dataset('penguins')
df.head()
```
|
5. gitignore 설정 (중요)
.gitignore:
1
2
3
4
5
6
7
| .venv/
.quarto/
_site/
__pycache__/
.ipynb_checkpoints/
_book/
_freeze/
|
포함해야 할 파일:
1
2
| pyproject.toml
uv.lock
|
6. GitHub 연결
6.1 초기화
1
2
3
| git init
git add .
git commit -m "init project"
|
6.2 원격 연결
1
2
3
| git remote add origin https://github.com/사용자명/eda-for-python.git
git branch -M main
git push -u origin main
|
7. GitHub Pages 설정
- Settings → Pages
- Source → GitHub Actions
8. 최초 배포
1
| uv run quarto publish gh-pages
|
9. GitHub Actions 구성
.github/workflows/publish.yml:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
| name: Publish Quarto Book (uv)
on:
push:
branches: [main]
permissions:
contents: write
jobs:
build-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install uv
run: pip install uv
- name: Install dependencies
run: |
uv sync
uv run python -m ipykernel install --user --name python3
- name: Setup Quarto
uses: quarto-dev/quarto-actions/setup@v2
- name: Render
run: uv run quarto render
- name: Publish
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
|
10. CI/CD 동작 확인
1
2
3
| git add .
git commit -m "update"
git push
|
확인:
- Actions 실행 여부
- gh-pages 브랜치 생성
- 웹 페이지 반영
접속:
1
| https://사용자명.github.io/eda-for-python/
|
11. 핵심 실행 구조
1
2
3
4
5
6
7
| uv 환경
↓
jupyter + ipykernel
↓
quarto render
↓
gh-pages 배포
|
12. 주요 에러 및 해결
1
| ModuleNotFoundError: No module named 'nbformat'
|
원인:
해결:
1
| uv add jupyter ipykernel
|
workflow에 추가:
1
| uv run python -m ipykernel install --user --name python3
|
12.2 uv.lock 파싱 에러
1
| extra `=`, expected nothing
|
원인:
해결:
금지:
12.3 권한 에러 (403)
1
| Permission denied to github-actions[bot]
|
해결:
1
2
| permissions:
contents: write
|
추가 확인:
- Settings → Actions → Read and write permissions
12.4 gh-pages 브랜치 없음
1
| does not have a branch named gh-pages
|
해결:
1
| uv run quarto publish gh-pages
|
12.5 404 Not Found
원인:
확인:
1
2
| Settings → Pages → GitHub Actions
https://username.github.io/repo/
|
12.6 PowerShell activate 오류
해결:
1
| Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
13. uv 사용 규칙
사용:
1
2
3
| uv add 패키지
uv sync
uv run 명령어
|
금지:
1
2
| uv pip compile
uv pip sync uv.lock
|
14. 프로젝트 구조
1
2
3
4
5
6
7
| eda-for-python/
├── pyproject.toml
├── uv.lock
├── _quarto.yml
├── index.qmd
├── .github/workflows/publish.yml
└── .gitignore
|
