GitHub Actions로 API 문서 자동 생성 및 배포하기

GitHub Actions로 API 문서 자동 생성 및 배포하기

(Cursor AI + Docstring + pdoc/mkdocs 통합 파이프라인)

AI 코딩 도구로 코드 생산성을 높였다면, 그다음은? 바로 문서 자동화입니다.
이 글에서는 Cursor AI로 자동 생성한 docstring을 기반으로 API 문서를 만들고, GitHub Actions를 통해 자동 배포하는 전체 파이프라인을 소개합니다. 특히 GitHub Actions를 처음 접하는 개발자를 위해, 개념부터 실전 예시까지 친절하게 설명할게요.

---

✅ 최종 워크플로우 요약

1. Cursor로 docstring 생성  
2. Git push → GitHub Actions 실행  
3. 문서 자동 생성 (pdoc or mkdocs)  
4. GitHub Pages로 자동 배포 🚀

---

🧠 GitHub Actions란?

GitHub Actions는 GitHub에서 제공하는 CI/CD(지속적 통합 및 배포) 자동화 도구입니다.

📌 주요 특징

기능	설명
💻 코드 기반 자동화	.github/workflows/ 폴더에 YAML 파일로 워크플로우 작성
🧩 다양한 트리거	push, pull_request, schedule 등으로 자동 실행 가능
🔧 실행 환경 제공	Ubuntu, macOS, Windows 컨테이너에서 실행
🤝 GitHub와 완벽 통합	GitHub 저장소 내에서 바로 설정 및 확인 가능
💸 무료 사용 가능	퍼블릭 저장소는 무제한, 개인도 일정 범위 무료 제공

쉽게 말해, "코드가 올라오면 알아서 빌드, 테스트, 배포까지 다 해주는 자동 비서"예요!

📌 작동 원리 요약

단계	설명
1️⃣	.github/workflows/ 폴더에 YAML 형식의 워크플로우 파일 생성
2️⃣	그 YAML 안에 on: push 같은 트리거 조건을 정의
3️⃣	설정된 조건에 따라 GitHub가 Actions를 자동으로 실행

---

🧾 예: 기본 워크플로우 구성

# .github/workflows/docs.yml

name: Generate Docs

on:
  push:
    branches: [ main ]   # main 브랜치에 push 될 때 자동 실행됨

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Do something...
      run: echo "✅ 자동으로 실행됐습니다!"

 

이렇게 설정해두고 main 브랜치에 커밋을 push하면, 자동으로 GitHub Actions가 작동해서 로그, 결과 등을 보여줍니다.

---

🚨 주의사항

조건	필요 조치
워크플로우 파일이 없음	자동 실행 안 됨 (Actions는 설정된 게 없다고 판단)
잘못된 YAML 문법	Actions 실행 실패
브랜치명이 다름	예: on: push → branches: [main]인데 develop에 push하면 실행 안 됨
GitHub Pages 배포 시	gh-pages 브랜치 설정도 따로 해줘야 함 (Settings > Pages)

---

✅ 요약

🔧 GitHub Actions는 자동으로 실행되지만, 설정 파일이 먼저 있어야 한다!

 

그래서 개발자가 반드시:

• .github/workflows/ 폴더에 YAML 파일을 작성하고
• on: 키워드로 실행 조건을 명시해줘야 해야합니다.

반응형

---

🛠️ 실전 예제: API 문서 자동 생성 & 배포

🧾 코드 예시 (math_ops.py)

def multiply(a: int, b: int) -> int:
    """
    Multiplies two numbers.

    Args:
        a (int): First number.
        b (int): Second number.

    Returns:
        int: The product of a and b.
    """
    return a * b

 

이와 같은 docstring은 Cursor에서 다음 명령으로 자동 생성 가능:

Add docstrings to all functions in this project

---

🔧 Step-by-Step: 자동화 파이프라인 구축하기

1️⃣ pdoc 설치 및 수동 테스트

pip install pdoc
pdoc math_ops.py --html --output-dir docs

 

👉 docs/ 폴더에 HTML 문서 생성 확인

---

2️⃣ GitHub Actions 워크플로우 파일 작성

.github/workflows/docs.yml 생성:

name: Generate and Deploy API Docs

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'

    - name: Install dependencies
      run: |
        pip install pdoc

    - name: Generate documentation
      run: |
        pdoc math_ops.py --html --output-dir docs

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs

모듈명이 다르다면 math_ops.py → 해당 모듈명으로 바꿔주세요!

---

3️⃣ GitHub Pages 설정

1. 저장소 → Settings → Pages
2. Source를 gh-pages 브랜치로 설정
3. /docs 디렉토리 선택

👉 커밋 후 자동으로 https://yourusername.github.io/your-repo-name/ 경로에 배포됨

---

🎯 mkdocs 사용 시 설정 변경

- name: Install dependencies
  run: |
    pip install mkdocs mkdocs-material

- name: Build docs
  run: |
    mkdocs build

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./site

mkdocs build는 site/ 폴더를 생성하며, 그게 배포 대상입니다.

---

💡 실전 활용 팁

팁	설명
커밋 메시지 필터링	특정 경로 (/src/, /api/) 변경 시에만 동작하도록 설정 가능
PR 트리거 사용	on: pull_request를 추가해 리뷰 단계에서 미리 문서 확인 가능
Slack/Discord 알림	워크플로우에 Webhook 추가하면 알림도 자동 발송 가능
코드 + 문서 통합 리뷰	문서까지 자동화하면 리뷰어의 부담이 줄어듦

---

🔁 전체 흐름 요약

1. Cursor로 함수별 docstring 생성
2. GitHub에 push → GitHub Actions 실행
3. 문서 자동 생성 (pdoc or mkdocs)
4. GitHub Pages로 자동 배포 완료!