Cursor AI + Docstring으로 만드는 자동 API 문서화 파이프라인 구축 가이드

Cursor AI + Docstring으로 만드는 자동 API 문서화 파이프라인 구축 가이드

AI 코딩 시대, 코드는 잘 짜는 것만큼 잘 설명하는 것도 중요합니다. Cursor AI를 사용하면 GPT-4의 힘으로 코드 문서화를 쉽게 자동화할 수 있습니다. 이번 글에서는 Cursor AI로 자동 생성한 docstring을 활용해 정식 API 문서를 만드는 전체 파이프라인을 소개합니다.

---

📌 이 글에서 배우는 것

• Docstring이 뭔지, 왜 중요한지
• Cursor AI로 docstring 자동 생성하는 방법
• pdoc, mkdocs를 활용해 문서화하는 전체 흐름
• 문서를 GitHub Pages 등에 배포하는 방법

---

🧠 Docstring이란?

Docstring은 Python에서 함수, 클래스, 모듈 등에 작성하는 설명용 주석 문자열입니다.

def greet(name):
    """
    이름을 받아 인사하는 메시지를 출력합니다.

    Args:
        name (str): 인사할 사람의 이름

    Returns:
        str: 인사 메시지
    """
    return f"Hello, {name}!"

✅ 특징

항목	설명
표준 문법	""" """ triple quotes로 감싸 사용
자동 문서화	help(), pdoc, Sphinx 등에서 읽어들일 수 있음
유지보수 향상	협업 시 함수 목적과 사용법을 쉽게 전달
API 문서의 기반	docstring이 API 문서의 핵심 재료가 됨

---

🧠 Cursor AI로 Docstring 자동 생성하기

👉 명령어 예시

Add docstrings to all functions in this file

 

또는 프로젝트 단위로:

Add docstrings to all functions in this project

 

Cursor는 전체 함수의 시그니처와 동작을 분석해 자동으로 """ 설명 """을 붙여줘요.

---

🛠️ 실전 예제 (math_ops.py)

🔴 원본 코드 (docstring 없음)

def multiply(a, b):
    return a * b

✅ Cursor 명령어 실행 후

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers and returns the result.

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

    Returns:
        int: The result of a multiplied by b.
    """
    return a * b

---

🔧 자동 문서화 파이프라인 구축하기

📦 1️⃣ pdoc 설치 및 실행

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

 

결과:

 

docs/
└── math_ops.html

 

브라우저로 열면 HTML API 문서를 확인할 수 있어요.

반응형

---

🌐 2️⃣ MkDocs로 정적 사이트 구성 (선택)

pip install mkdocs
mkdocs new my-docs
cd my-docs

 

docs/ 폴더에 생성된 HTML 파일을 넣고, mkdocs.yml 수정:

nav:
  - Home: index.md
  - API Docs: math_ops.html

 

빌드 & 확인:

mkdocs serve

 

로컬 웹사이트 열기: http://127.0.0.1:8000

---

🚀 3️⃣ GitHub Pages 또는 Netlify로 배포

mkdocs gh-deploy

 

정적 사이트가 GitHub Pages를 통해 배포됩니다.
Netlify, Vercel로도 간단하게 배포 가능!

---

🔁 전체 파이프라인 요약

1. Cursor로 docstring 자동 생성
2. pdoc으로 HTML 문서 생성
3. mkdocs로 구조화 및 스타일링
4. GitHub Pages로 배포

 

---

💡 실전 팁

상황	팁
대규모 프로젝트	pdoc your_package/ --html --output-dir docs
다국어 팀	Translate this docstring to Korean 가능
문서 자동화	GitHub Actions에 pdoc/mkdocs 통합 가능
문서 커스터마이징	mkdocs-material 테마 사용 추천 (pip install mkdocs-material)

---

🧩 활용 시나리오

• 클라이언트에게 API 설명서를 자동 전달
• 오픈소스 프로젝트의 사용법 공개
• 백엔드/프론트엔드 간 인터페이스 공유
• 신입 개발자 온보딩 자료로 활용