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 공식 문서

정보기술에서, 레거시 프로그램과 데이터는 프로그래밍 언어, 
플랫폼 그리고 기술 등에 있어, 과거로 부터 물려 내려온 것들을 의미한다. 
컴퓨터를 사용하는 대부분의 기업들은 중요한 업무를 처리하는 레거시 응용프로그램들과 데이터베이스를 가지고 있다. 
문제는, 대체로 새로운 기술과 프로그래머의 솜씨를 사용한 새롭고 보다 효율적인 코드로 변환하는 동안, 
레거시 프로그램을 계속 운영시켜야 하는데 있다. 
과거에는, 많은 프로그램들이 특정업체의 운영체계에 맞게 작성되어왔다. 
현재, 많은 회사들이 자신들의 레거시 프로그램들을 개방형이나, 표준 프로그래밍 인터페이스를 따르는 새로운 프로그래밍 언어와 운영체계에 맞게 변환하고 있다. 
미래에는 응용프로그램들을 재작성하지 않고 새롭게 갱신하는 일이 보다 쉬워질 것이며, 기업들은 어떤 회사의 운영체계에서도 자신들의 응용프로그램을 그대로 사용할 수 있게 될 것이다.

새로운 언어로 바꾸는 것 외에도, 기업들은 응용프로그램과 데이터의 위치를 재배치하고 있다. 
일반적으로 레거시 시스템들은 그것들을 개발했던 플랫폼에서만 운영될 수 있었다. 
대체로 새로운 개발환경은 레거시 시스템과 데이터를 계속 지원해야할 필요에 대해 책임을 진다. 
많은 새로운 도구들을 이용하여, 새로운 프로그램이 레거시 데이터베이스들을 액세스할 수 있다.

출처 : http://www.terms.co.kr/legacy.htm

1. 깃허브 코파일럿 ( github copilot )
   • AI 기반으로 작성중인 코드를 분석해 적절한 코드를 제안하는 서비스.
   • 마이크로 소프트가 지원한 AI 연구 스타트업 오픈AI와 깃허브가 공동으로 협력한 작품
   • 코파일럿이 코드 작성 부분에 대해 적절하게 제안 -> 이에 대해 수락 or 거절 가능
   • 장점
     • 코딩 시간 단축 : 잘 만들어 진 기본 틀을 바탕으로 더 질좋은 소프트웨어 개발 가능.
     • 다양한 소프트웨어 개발 방법론을 바탕으로 구현 된 오픈소스 소프트웨어를 보다 빠르게 사용 가능.
     • API 설명서를 읽으며 코드를 꼼꼼히 살펴보는 시간을 단축
     • 새로운 언어를 습득하는데 도움을 줄 수 있음. 

1. 뉴스
   • 2022년 여름 출시 예정
   • CIO 뉴스레터
     • 연례 빌드 컨퍼런스에서 마이크로소프트는 깃허브 코파일럿이 올여름 GA 버전으로 전환된다는 소식을 알렸다. 깃허브 코파일럿은 비주얼 스튜디오 코드(Visual Studio Code), 네오빔(Neovim), 젯브레인 IDE(JetBrains IDEs)의 확장 프로그램으로 사용할 수 있다. 마이크로소프트는 깃허브의 모회사다. 
       
       깃허브 코파일럿은 공개적으로 사용 가능한 수십억 줄의 소스코드와 자연어를 학습한 AI 시스템 ‘오픈AI 코덱스(OpenAI Codex)’를 기반으로 한다. 한편 작업 중인 코드의 맥락을 활용하는 이 도구와 관련해 자유 소프트웨어 재단(Free Software Foundation)은 무료 라이선스 소스코드 사용의 합법성과 윤리에 의문을 제기해왔다. 
        
       --> 칼럼ㅣ깃허브 코파일럿에서 ‘희망’을 보았다
       --> “깃허브 코파일럿, 용납할 수 없고 부당하다” 자유 소프트웨어 재단
       --> 칼럼 | '미래는 좀처럼 오지 않는다'··· 깃허브 코파일럿을 둘러싼 호들갑
       --> 깃허브 코파일럿, 개발자 반응은?··· "놀랍도록 유용"vs"아직 미흡"
       
       원문보기:
       https://www.ciokorea.com/news/237649#csidxe84d4a6663290a6977a351453cf2ac4