Python Sphinx 도구란?

• Sphinx는 Python 프로젝트의 문서 자동화 생성 도구입니다.
• 코드에 작성된 docstring을 기반으로 HTML, PDF, ePub 등 다양한 형식의 문서를 자동으로 생성할 수 있습니다.
• 주로 오픈소스 프로젝트, 라이브러리, API 문서화에 널리 사용됩니다.
• reStructuredText(.rst) 마크업 언어를 사용하며, 확장 기능(Extension)도 풍부합니다.

설치 방법

pip install sphinx
    

기본 사용 예시

1. 프로젝트 폴더에서 Sphinx 초기화

sphinx-quickstart
    

• 질문에 따라 프로젝트명, 문서 경로 등을 입력하면 conf.py, index.rst 등이 생성됩니다.

2. 코드에 docstring 작성

def add(x, y):
    """
    두 수를 더합니다.

    :param x: 첫 번째 수
    :param y: 두 번째 수
    :return: 두 수의 합
    """
    return x + y
    

3. API 문서 자동 생성 (예: autodoc 확장 사용)

# conf.py에 아래 추가
extensions = ['sphinx.ext.autodoc']

# index.rst에 아래 추가
.. automodule:: mymodule
    :members:
    

4. HTML 문서 빌드

make html
    

• _build/html 폴더에 HTML 문서가 생성됩니다.

주요 특징

• 코드와 문서의 일관성 유지 (docstring 기반)
• 자동 목차, API 문서, 수식, 코드 하이라이트 등 지원
• Read the Docs 등과 연동 가능

요약

• Sphinx는 Python 프로젝트의 문서를 쉽고 체계적으로 자동 생성해주는 강력한 도구입니다.
• 코드에 docstring만 잘 작성하면, 다양한 형식의 문서를 손쉽게 만들 수 있습니다.

ch02_ex5.py에서 자주 쓰이는 타입 힌트와 함수 설명

1. isinstance()

• 파이썬 내장 함수로, 객체가 특정 클래스(혹은 그 하위 클래스)의 인스턴스인지 확인할 때 사용합니다.
• 문법: isinstance(객체, 클래스)
• 여러 타입을 튜플로 전달 가능: isinstance(x, (int, float))

class A: pass
class B(A): pass
b = B()
print(isinstance(b, A))  # True (B는 A의 하위 클래스)

2. cast() (typing 모듈)

• 정적 타입 검사기(예: mypy)에게 "이 값은 내가 지정한 타입이라고 간주해라"라고 알려주는 용도입니다.
• 런타임에는 아무런 변환도 하지 않고, 값 자체를 그대로 반환합니다.
• 잘못된 타입을 cast해도 런타임 오류는 발생하지 않지만, 실제 사용 시 타입이 맞지 않으면 AttributeError 등은 발생할 수 있습니다.

from typing import cast

def foo(x: object):
    y = cast(str, x)  # 타입 검사기에게 y는 str이라고 알려줌
    return y

3. @overload (typing 모듈)

• 함수나 메서드가 여러 가지 시그니처(입력 타입/개수)에 따라 다르게 동작할 수 있음을 타입 검사기에게 알려주는 데코레이터입니다.
• 실제 구현은 마지막에 한 번만 작성하고, 그 위에 여러 개의 @overload 시그니처를 선언합니다.
• 런타임에는 아무 영향이 없고, 타입 검사기만 참고합니다.

from typing import overload

@overload
def func(x: int) -> int: ...
@overload
def func(x: str) -> str: ...
def func(x):
    # 실제 구현
    if isinstance(x, int):
        return x + 1
    return x.upper()

4. Union[] (typing 모듈)

• 여러 타입 중 하나가 올 수 있음을 명시합니다.
• 예시: Union[int, str]는 int 또는 str 타입이 올 수 있음을 의미합니다.

from typing import Union

def foo(x: Union[int, str]):
    print(x)

5. Optional[] (typing 모듈)

• 특정 타입 또는 None이 올 수 있음을 명시합니다.
• Optional[X]는 Union[X, None]과 같습니다.

from typing import Optional

def foo(x: Optional[int]):
    if x is not None:
        print(x + 1)
    else:
        print("None!")

6. 실전 예시 (Hand4 생성자)

class Hand4:
    @overload
    def __init__(self, arg1: "Hand4") -> None: ...
    @overload
    def __init__(self, arg1: "Hand4", arg2: Card, *, split: int) -> None: ...
    @overload
    def __init__(self, arg1: Card, arg2: Card, arg3: Card) -> None: ...
    def __init__(self, arg1: Union["Hand4", Card], arg2: Optional[Card]=None, arg3: Optional[Card]=None, split: Optional[int]=None):
        # ...구현 생략...

• 이렇게 여러 생성자 시그니처를 타입 검사기에 명확히 알려줄 수 있습니다.

7. 참고 자료

• 파이썬 공식 typing 문서
• mypy 공식 문서