📚 왜 문서화는 항상 미루게 될까?

솔직히 말해보자. 코드 짜는 건 재밌는데 문서 쓰는 건 정말... 지루하지 않나? 😅
나도 그랬다. 멋진 API를 만들어놓고 나중에 "이거 어떻게 쓰는 거였지?"라며 내 코드를 다시 뜯어보는 경험, 한 번쯤은 있을 거다.

더 웃긴 건 팀원이 "이 함수 파라미터가 뭐예요?"라고 물어볼 때다. 분명 3개월 전에 내가 만든 건데 기억이 안 나서 코드를 다시 읽어야 하는 상황. 🤦‍♂️

이런 문제를 해결하기 위해 등장한 게 바로 자동 문서화 도구다. 그중에서도 Python 생태계에서 가장 널리 사용되는 Sphinx는 정말 강력한 도구다.

🎯 Sphinx가 뭐길래?

Sphinx는 원래 Python 공식 문서를 만들기 위해 개발된 도구다. 📖
지금은 Python뿐만 아니라 C, C++, JavaScript 등 다양한 언어의 문서화에도 사용되고 있다.

Sphinx의 핵심 기능은 이렇다:

특히 재능넷 같은 플랫폼에서 프로그래밍 관련 재능을 공유할 때, 잘 정리된 API 문서는 신뢰도를 크게 높여준다. 💼
"이 사람은 전문가구나"라는 인상을 주는 가장 확실한 방법이기도 하다.

📝 Docstring 작성의 기술

Sphinx가 자동으로 문서를 만들어주려면, 코드에 제대로 된 docstring이 있어야 한다. ✍️
Docstring은 함수, 클래스, 모듈 바로 아래에 작성하는 설명 문자열이다.

Python에는 여러 docstring 스타일이 있는데, Sphinx와 가장 잘 맞는 건 다음 세 가지다:

1️⃣ Google Style (가장 인기 있음)

def calculate_total(price, quantity, discount=0):
    """상품의 최종 가격을 계산합니다.
    
    이 함수는 기본 가격에 수량을 곱하고 할인을 적용하여
    최종 결제 금액을 반환합니다.
    
    Args:
        price (float): 상품의 단가
        quantity (int): 구매 수량
        discount (float, optional): 할인율 (0~1 사이). 기본값은 0.
    
    Returns:
        float: 할인이 적용된 최종 가격
    
    Raises:
        ValueError: price나 quantity가 음수일 경우
        
    Examples:
        >>> calculate_total(1000, 2, 0.1)
        1800.0
        
        >>> calculate_total(500, 3)
        1500.0
    """
    if price < 0 or quantity < 0:
        raise ValueError("가격과 수량은 양수여야 합니다")
    
    subtotal = price * quantity
    return subtotal * (1 - discount)

2️⃣ NumPy Style (과학 계산 분야에서 선호)

def calculate_total(price, quantity, discount=0):
    """
    상품의 최종 가격을 계산합니다.
    
    이 함수는 기본 가격에 수량을 곱하고 할인을 적용하여
    최종 결제 금액을 반환합니다.
    
    Parameters
    ----------
    price : float
        상품의 단가
    quantity : int
        구매 수량
    discount : float, optional
        할인율 (0~1 사이), 기본값은 0
    
    Returns
    -------
    float
        할인이 적용된 최종 가격
    
    Raises
    ------
    ValueError
        price나 quantity가 음수일 경우
    
    Examples
    --------
    >>> calculate_total(1000, 2, 0.1)
    1800.0
    """
    if price < 0 or quantity < 0:
        raise ValueError("가격과 수량은 양수여야 합니다")
    
    subtotal = price * quantity
    return subtotal * (1 - discount)

3️⃣ Sphinx Style (전통적인 방식)

def calculate_total(price, quantity, discount=0):
    """상품의 최종 가격을 계산합니다.
    
    이 함수는 기본 가격에 수량을 곱하고 할인을 적용하여
    최종 결제 금액을 반환합니다.
    
    :param price: 상품의 단가
    :type price: float
    :param quantity: 구매 수량
    :type quantity: int
    :param discount: 할인율 (0~1 사이), 기본값은 0
    :type discount: float
    :return: 할인이 적용된 최종 가격
    :rtype: float
    :raises ValueError: price나 quantity가 음수일 경우
    
    Example::
    
        >>> calculate_total(1000, 2, 0.1)
        1800.0
    """
    if price < 0 or quantity < 0:
        raise ValueError("가격과 수량은 양수여야 합니다")
    
    subtotal = price * quantity
    return subtotal * (1 - discount)

🏗️ 클래스 문서화 예제

class ShoppingCart:
    """온라인 쇼핑몰의 장바구니를 관리하는 클래스입니다.
    
    이 클래스는 상품 추가, 제거, 총액 계산 등의 기능을 제공합니다.
    
    Attributes:
        items (list): 장바구니에 담긴 상품 목록
        user_id (str): 사용자 식별자
        
    Examples:
        >>> cart = ShoppingCart("user123")
        >>> cart.add_item("노트북", 1500000, 1)
        >>> cart.get_total()
        1500000
    """
    
    def __init__(self, user_id):
        """ShoppingCart 인스턴스를 초기화합니다.
        
        Args:
            user_id (str): 사용자 식별자
        """
        self.items = []
        self.user_id = user_id
    
    def add_item(self, name, price, quantity=1):
        """장바구니에 상품을 추가합니다.
        
        Args:
            name (str): 상품명
            price (float): 상품 가격
            quantity (int, optional): 수량. 기본값은 1.
            
        Returns:
            bool: 추가 성공 여부
            
        Raises:
            ValueError: 가격이나 수량이 유효하지 않을 경우
        """
        if price <= 0 or quantity <= 0:
            raise ValueError("가격과 수량은 양수여야 합니다")
        
        self.items.append({
            'name': name,
            'price': price,
            'quantity': quantity
        })
        return True
    
    def get_total(self):
        """장바구니의 총 금액을 계산합니다.
        
        Returns:
            float: 모든 상품의 총 가격
        """
        return sum(item['price'] * item['quantity'] for item in self.items)

🏗️ 실전 프로젝트 구조

이론은 충분히 배웠으니, 이제 실제 프로젝트에 어떻게 적용하는지 보자. 🛠️
전형적인 Python 프로젝트 구조는 다음과 같다:

my_project/
├── docs/
│   ├── source/
│   │   ├── conf.py
│   │   ├── index.rst
│   │   ├── installation.rst
│   │   ├── quickstart.rst
│   │   ├── api/
│   │   │   ├── modules.rst
│   │   │   └── mypackage.rst
│   │   └── _static/
│   │       └── custom.css
│   ├── build/
│   │   └── html/
│   └── Makefile
├── mypackage/
│   ├── __init__.py
│   ├── core.py
│   ├── utils.py
│   └── models/
│       ├── __init__.py
│       └── user.py
├── tests/
│   └── test_core.py
├── setup.py
├── requirements.txt
└── README.md

📦 실제 모듈 예제

간단한 사용자 관리 시스템을 만들어보자. 실제로 문서화가 어떻게 되는지 확인할 수 있다.

# mypackage/models/user.py

from typing import Optional, List
from datetime import datetime

class User:
    """사용자 정보를 관리하는 클래스입니다.
    
    이 클래스는 사용자의 기본 정보와 권한을 관리하며,
    데이터베이스와의 상호작용을 추상화합니다.
    
    Attributes:
        user_id (str): 사용자 고유 식별자
        username (str): 사용자명
        email (str): 이메일 주소
        created_at (datetime): 계정 생성 시간
        is_active (bool): 계정 활성화 상태
        roles (List[str]): 사용자 권한 목록
        
    Examples:
        >>> user = User("user123", "john_doe", "john@example.com")
        >>> user.add_role("admin")
        >>> user.has_role("admin")
        True
        
    Note:
        사용자 비밀번호는 별도의 보안 모듈에서 관리됩니다.
        이 클래스는 인증 정보를 직접 다루지 않습니다.
    """
    
    def __init__(
        self, 
        user_id: str, 
        username: str, 
        email: str,
        is_active: bool = True
    ):
        """User 인스턴스를 초기화합니다.
        
        Args:
            user_id: 사용자 고유 식별자 (UUID 권장)
            username: 사용자명 (3-20자, 영문/숫자/언더스코어)
            email: 이메일 주소 (유효한 형식이어야 함)
            is_active: 계정 활성화 상태 (기본값: True)
            
        Raises:
            ValueError: username이나 email 형식이 올바르지 않을 경우
        """
        self.user_id = user_id
        self.username = username
        self.email = email
        self.created_at = datetime.now()
        self.is_active = is_active
        self.roles: List[str] = []
        
    def add_role(self, role: str) -> bool:
        """사용자에게 권한을 추가합니다.
        
        Args:
            role: 추가할 권한 이름 (예: 'admin', 'editor', 'viewer')
            
        Returns:
            권한 추가 성공 여부
            
        Raises:
            ValueError: 이미 존재하는 권한일 경우
            
        Examples:
            >>> user.add_role("editor")
            True
            >>> user.add_role("editor")  # 중복
            ValueError: Role 'editor' already exists
        """
        if role in self.roles:
            raise ValueError(f"Role '{role}' already exists")
        self.roles.append(role)
        return True
    
    def remove_role(self, role: str) -> bool:
        """사용자의 권한을 제거합니다.
        
        Args:
            role: 제거할 권한 이름
            
        Returns:
            권한 제거 성공 여부
            
        Raises:
            ValueError: 존재하지 않는 권한일 경우
        """
        if role not in self.roles:
            raise ValueError(f"Role '{role}' not found")
        self.roles.remove(role)
        return True
    
    def has_role(self, role: str) -> bool:
        """사용자가 특정 권한을 가지고 있는지 확인합니다.
        
        Args:
            role: 확인할 권한 이름
            
        Returns:
            권한 보유 여부
            
        Examples:
            >>> user.add_role("admin")
            >>> user.has_role("admin")
            True
            >>> user.has_role("superuser")
            False
        """
        return role in self.roles
    
    def deactivate(self) -> None:
        """사용자 계정을 비활성화합니다.
        
        비활성화된 계정은 로그인할 수 없으며,
        모든 세션이 즉시 종료됩니다.
        
        Warning:
            이 작업은 되돌릴 수 있지만, 진행 중인 작업이
            모두 중단되므로 신중하게 사용해야 합니다.
        """
        self.is_active = False
    
    def activate(self) -> None:
        """사용자 계정을 활성화합니다.
        
        비활성화된 계정을 다시 활성화하여
        정상적인 서비스 이용이 가능하도록 합니다.
        """
        self.is_active = True
    
    def to_dict(self) -> dict:
        """사용자 정보를 딕셔너리로 변환합니다.
        
        Returns:
            사용자 정보가 담긴 딕셔너리
            
        Examples:
            >>> user.to_dict()
            {
                'user_id': 'user123',
                'username': 'john_doe',
                'email': 'john@example.com',
                'is_active': True,
                'roles': ['admin', 'editor']
            }
        """
        return {
            'user_id': self.user_id,
            'username': self.username,
            'email': self.email,
            'created_at': self.created_at.isoformat(),
            'is_active': self.is_active,
            'roles': self.roles
        }

🔧 유틸리티 함수 예제

# mypackage/utils.py

from typing import List, Optional
import re

def validate_email(email: str) -> bool:
    """이메일 주소의 유효성을 검증합니다.
    
    RFC 5322 표준을 기반으로 이메일 형식을 검증합니다.
    단, 완벽한 검증은 아니며 일반적인 케이스를 커버합니다.
    
    Args:
        email: 검증할 이메일 주소
        
    Returns:
        유효한 이메일이면 True, 아니면 False
        
    Examples:
        >>> validate_email("user@example.com")
        True
        >>> validate_email("invalid.email")
        False
        >>> validate_email("user@sub.domain.com")
        True
        
    Note:
        이 함수는 형식만 검증하며, 실제 이메일 주소의
        존재 여부는 확인하지 않습니다.
    """
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

def validate_username(username: str) -> bool:
    """사용자명의 유효성을 검증합니다.
    
    사용자명은 다음 규칙을 따라야 합니다:
    - 3자 이상 20자 이하
    - 영문자, 숫자, 언더스코어만 허용
    - 영문자로 시작해야 함
    
    Args:
        username: 검증할 사용자명
        
    Returns:
        유효한 사용자명이면 True, 아니면 False
        
    Examples:
        >>> validate_username("john_doe")
        True
        >>> validate_username("ab")  # 너무 짧음
        False
        >>> validate_username("123user")  # 숫자로 시작
        False
    """
    if not 3 <= len(username) <= 20:
        return False
    pattern = r'^[a-zA-Z][a-zA-Z0-9_]*$'
    return bool(re.match(pattern, username))

def search_users(
    users: List['User'], 
    query: str, 
    field: str = 'username'
) -> List['User']:
    """사용자 목록에서 특정 조건에 맞는 사용자를 검색합니다.
    
    대소문자를 구분하지 않는 부분 일치 검색을 수행합니다.
    
    Args:
        users: 검색할 사용자 목록
        query: 검색어
        field: 검색할 필드 ('username', 'email', 'user_id')
        
    Returns:
        검색 조건에 맞는 사용자 목록
        
    Raises:
        ValueError: 지원하지 않는 필드를 지정한 경우
        
    Examples:
        >>> users = [user1, user2, user3]
        >>> results = search_users(users, "john", "username")
        >>> len(results)
        2
        
    See Also:
        :func:`filter_active_users`: 활성 사용자만 필터링
    """
    if field not in ['username', 'email', 'user_id']:
        raise ValueError(f"Unsupported field: {field}")
    
    query_lower = query.lower()
    return [
        user for user in users 
        if query_lower in getattr(user, field).lower()
    ]

def filter_active_users(users: List['User']) -> List['User']:
    """활성화된 사용자만 필터링합니다.
    
    Args:
        users: 필터링할 사용자 목록
        
    Returns:
        활성 상태인 사용자 목록
        
    Examples:
        >>> all_users = [active_user, inactive_user, active_user2]
        >>> active_only = filter_active_users(all_users)
        >>> len(active_only)
        2
    """
    return [user for user in users if user.is_active]

🎨 문서 빌드하기

코드와 docstring 작성이 끝났으면 이제 실제로 문서를 생성할 차례다! 🎉

🔨 빌드 명령어

# docs 디렉토리로 이동
cd docs

# HTML 문서 생성
make html

# Windows에서는
make.bat html

# 또는 직접 sphinx-build 사용
sphinx-build -b html source build/html

# PDF 생성 (LaTeX 필요)
make latexpdf

# ePub 생성
make epub

# 빌드 결과 삭제
make clean

빌드가 성공하면 docs/build/html/index.html 파일이 생성된다.
브라우저로 열어보면 멋진 문서가 완성되어 있을 거다! 🌟

🐛 흔한 에러와 해결법

🤝 팀 협업과 문서화 문화

기술적인 부분도 중요하지만, 팀 전체가 문서화를 습관화하는 게 더 중요하다. 👥
재능넷에서 프로그래밍 재능을 공유할 때도, 잘 정리된 문서는 신뢰도를 크게 높여준다.

📋 문서화 체크리스트

🎓 좋은 문서의 특징

🚫 피해야 할 안티패턴

# ❌ 나쁜 예: 너무 간단함
def calc(a, b):
    """계산"""
    return a + b

# ❌ 나쁜 예: 코드 반복
def add_numbers(x, y):
    """add_numbers는 x와 y를 더한다"""
    return x + y

# ❌ 나쁜 예: 구현 세부사항만 설명
def process(data):
    """for 루프를 돌면서 각 항목을 처리한다"""
    pass

# ✅ 좋은 예: 명확하고 완전함
def calculate_discount(
    original_price: float, 
    discount_rate: float
) -> float:
    """상품의 할인 가격을 계산합니다.
    
    원가에 할인율을 적용하여 최종 가격을 반환합니다.
    할인율은 0과 1 사이의 값이어야 합니다.
    
    Args:
        original_price: 상품의 원가 (양수)
        discount_rate: 할인율 (0.0 ~ 1.0)
        
    Returns:
        할인이 적용된 최종 가격
        
    Raises:
        ValueError: 가격이 음수이거나 할인율이 범위를 벗어난 경우
        
    Examples:
        >>> calculate_discount(10000, 0.2)
        8000.0
        
        >>> calculate_discount(5000, 0.5)
        2500.0
    """
    if original_price < 0:
        raise ValueError("가격은 양수여야 합니다")
    if not 0 <= discount_rate <= 1:
        raise ValueError("할인율은 0과 1 사이여야 합니다")
    
    return original_price * (1 - discount_rate)

🎬 실전 프로젝트: 완전한 예제

이제 배운 내용을 모두 종합해서 실제 프로젝트를 만들어보자! 🎯
간단한 REST API 클라이언트 라이브러리를 만들고 문서화해보겠다.

📁 프로젝트 구조

api-client/
├── apiclient/
│   ├── __init__.py
│   ├── client.py
│   ├── exceptions.py
│   └── models.py
├── docs/
│   ├── source/
│   │   ├── conf.py
│   │   ├── index.rst
│   │   ├── quickstart.rst
│   │   ├── api.rst
│   │   └── examples.rst
│   └── Makefile
├── tests/
│   └── test_client.py
├── setup.py
├── requirements.txt
└── README.md

💻 코드 구현

# apiclient/exceptions.py

class APIClientError(Exception):
    """API 클라이언트의 기본 예외 클래스입니다.
    
    모든 커스텀 예외는 이 클래스를 상속합니다.
    """
    pass

class AuthenticationError(APIClientError):
    """인증 실패 시 발생하는 예외입니다.
    
    API 키가 유효하지 않거나 만료된 경우 발생합니다.
    
    Attributes:
        message: 에러 메시지
        status_code: HTTP 상태 코드
    """
    
    def __init__(self, message: str, status_code: int = 401):
        self.message = message
        self.status_code = status_code
        super().__init__(self.message)

class RateLimitError(APIClientError):
    """API 호출 제한을 초과했을 때 발생하는 예외입니다.
    
    Attributes:
        retry_after: 재시도 가능한 시간 (초)
    """
    
    def __init__(self, retry_after: int):
        self.retry_after = retry_after
        super().__init__(f"Rate limit exceeded. Retry after {retry_after} seconds")

# apiclient/models.py

from dataclasses import dataclass
from typing import Optional, Dict, Any
from datetime import datetime

@dataclass
class APIResponse:
    """API 응답을 나타내는 데이터 클래스입니다.
    
    모든 API 호출의 결과는 이 클래스의 인스턴스로 반환됩니다.
    
    Attributes:
        status_code: HTTP 상태 코드
        data: 응답 데이터 (JSON)
        headers: 응답 헤더
        timestamp: 응답 시간
        
    Examples:
        >>> response = APIResponse(200, {"result": "success"}, {})
        >>> response.is_success()
        True
    """
    
    status_code: int
    data: Dict[str, Any]
    headers: Dict[str, str]
    timestamp: datetime = None
    
    def __post_init__(self):
        if self.timestamp is None:
            self.timestamp = datetime.now()
    
    def is_success(self) -> bool:
        """응답이 성공인지 확인합니다.
        
        Returns:
            200번대 상태 코드면 True, 아니면 False
        """
        return 200 <= self.status_code < 300
    
    def get(self, key: str, default: Any = None) -> Any:
        """응답 데이터에서 특정 키의 값을 가져옵니다.
        
        Args:
            key: 가져올 키
            default: 키가 없을 때 반환할 기본값
            
        Returns:
            키에 해당하는 값 또는 기본값
        """
        return self.data.get(key, default)

# apiclient/client.py

import requests
from typing import Optional, Dict, Any
from .models import APIResponse
from .exceptions import AuthenticationError, RateLimitError, APIClientError

class APIClient:
    """REST API와 통신하기 위한 클라이언트입니다.
    
    이 클래스는 HTTP 요청을 추상화하고, 인증, 에러 처리,
    재시도 로직 등을 제공합니다.
    
    Attributes:
        base_url: API의 기본 URL
        api_key: 인증에 사용할 API 키
        timeout: 요청 타임아웃 (초)
        
    Examples:
        >>> client = APIClient("https://api.example.com", "your-api-key")
        >>> response = client.get("/users/123")
        >>> print(response.data)
        {'id': 123, 'name': 'John Doe'}
        
    Note:
        이 클라이언트는 자동으로 재시도를 수행하지 않습니다.
        재시도가 필요한 경우 별도로 구현해야 합니다.
    """
    
    def __init__(
        self, 
        base_url: str, 
        api_key: str,
        timeout: int = 30
    ):
        """APIClient 인스턴스를 초기화합니다.
        
        Args:
            base_url: API의 기본 URL (예: "https://api.example.com")
            api_key: 인증에 사용할 API 키
            timeout: 요청 타임아웃 (초). 기본값은 30.
            
        Raises:
            ValueError: base_url이나 api_key가 비어있는 경우
        """
        if not base_url or not api_key:
            raise ValueError("base_url and api_key are required")
        
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.timeout = timeout
        self._session = requests.Session()
        self._session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def get(
        self, 
        endpoint: str, 
        params: Optional[Dict[str, Any]] = None
    ) -> APIResponse:
        """GET 요청을 수행합니다.
        
        Args:
            endpoint: API 엔드포인트 (예: "/users/123")
            params: 쿼리 파라미터 (선택사항)
            
        Returns:
            API 응답을 담은 APIResponse 객체
            
        Raises:
            AuthenticationError: 인증 실패 시
            RateLimitError: API 호출 제한 초과 시
            APIClientError: 기타 API 에러
            
        Examples:
            >>> response = client.get("/users", params={"page": 1})
            >>> users = response.data['users']
        """
        return self._request('GET', endpoint, params=params)
    
    def post(
        self, 
        endpoint: str, 
        data: Optional[Dict[str, Any]] = None
    ) -> APIResponse:
        """POST 요청을 수행합니다.
        
        Args:
            endpoint: API 엔드포인트
            data: 요청 본문 데이터
            
        Returns:
            API 응답을 담은 APIResponse 객체
            
        Raises:
            AuthenticationError: 인증 실패 시
            RateLimitError: API 호출 제한 초과 시
            APIClientError: 기타 API 에러
        """
        return self._request('POST', endpoint, json=data)
    
    def _request(
        self, 
        method: str, 
        endpoint: str, 
        **kwargs
    ) -> APIResponse:
        """실제 HTTP 요청을 수행하는 내부 메서드입니다.
        
        Args:
            method: HTTP 메서드 (GET, POST 등)
            endpoint: API 엔드포인트
            **kwargs: requests 라이브러리에 전달할 추가 인자
            
        Returns:
            API 응답
            
        Raises:
            AuthenticationError: 401 응답 시
            RateLimitError: 429 응답 시
            APIClientError: 기타 에러
        """
        url = f"{self.base_url}{endpoint}"
        
        try:
            response = self._session.request(
                method, 
                url, 
                timeout=self.timeout,
                **kwargs
            )
            
            if response.status_code == 401:
                raise AuthenticationError("Invalid API key")
            
            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                raise RateLimitError(retry_after)
            
            return APIResponse(
                status_code=response.status_code,
                data=response.json() if response.content else {},
                headers=dict(response.headers)
            )
            
        except requests.exceptions.Timeout:
            raise APIClientError(f"Request timeout after {self.timeout} seconds")
        except requests.exceptions.RequestException as e:
            raise APIClientError(f"Request failed: {str(e)}")
    
    def close(self):
        """세션을 종료합니다.
        
        리소스를 정리하기 위해 사용이 끝나면 호출해야 합니다.
        
        Examples:
            >>> client = APIClient(base_url, api_key)
            >>> try:
            ...     response = client.get("/data")
            ... finally:
            ...     client.close()
        """
        self._session.close()
    
    def __enter__(self):
        """컨텍스트 매니저 진입."""
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        """컨텍스트 매니저 종료."""
        self.close()

📖 문서 작성

.. quickstart.rst

빠른 시작
=========

설치
----

pip를 사용하여 설치할 수 있습니다:

.. code-block:: bash

   pip install api-client

기본 사용법
-----------

API 클라이언트를 사용하는 가장 간단한 방법입니다:

.. code-block:: python

   from apiclient import APIClient
   
   # 클라이언트 생성
   client = APIClient(
       base_url="https://api.example.com",
       api_key="your-api-key-here"
   )
   
   # GET 요청
   response = client.get("/users/123")
   print(response.data)
   
   # POST 요청
   new_user = {
       "name": "John Doe",
       "email": "john@example.com"
   }
   response = client.post("/users", data=new_user)
   
   # 세션 종료
   client.close()

컨텍스트 매니저 사용
--------------------

자동으로 리소스를 정리하려면 컨텍스트 매니저를 사용하세요:

.. code-block:: python

   with APIClient(base_url, api_key) as client:
       response = client.get("/data")
       # 자동으로 close() 호출됨

에러 처리
---------

다양한 예외를 처리할 수 있습니다:

.. code-block:: python

   from apiclient import APIClient
   from apiclient.exceptions import (
       AuthenticationError,
       RateLimitError,
       APIClientError
   )
   
   try:
       with APIClient(base_url, api_key) as client:
           response = client.get("/data")
           
   except AuthenticationError:
       print("API 키가 유효하지 않습니다")
       
   except RateLimitError as e:
       print(f"{e.retry_after}초 후에 재시도하세요")
       
   except APIClientError as e:
       print(f"API 에러: {e}")

다음 단계
---------

* :doc:`api` - 전체 API 레퍼런스
* :doc:`examples` - 더 많은 예제

이렇게 완성된 프로젝트는 전문적이고 사용하기 쉬운 문서를 갖추게 된다! 🎉

🎓 마치며

여기까지 Python 문서화와 Sphinx를 활용한 API 문서 자동 생성에 대해 알아봤다. 🎊

처음에는 복잡해 보일 수 있지만, 한 번 설정해두면 정말 편하다.
코드를 작성하면서 docstring만 잘 작성하면, 나머지는 Sphinx가 알아서 해준다!

특히 재능넷 같은 플랫폼에서 프로그래밍 재능을 공유할 때,
잘 정리된 문서는 당신의 전문성을 보여주는 최고의 명함이 된다. 💼

문서화는 단순히 귀찮은 작업이 아니라,
미래의 당신과 팀원들에게 주는 선물이다. 🎁

오늘부터 당장 시작해보자!
작은 프로젝트라도 문서화 습관을 들이면,
나중에 큰 프로젝트에서 엄청난 시간을 절약할 수 있다.

이제 당신도 문서화 마스터다! 🏆
멋진 문서를 만들어서 세상과 공유해보자!

Happy Documenting! 📚✨