[Sphinx] 코드 문서에서 주의할 점

코드 문서에서 주의할 점

 

 

주석은 코드를 명확하게 한다. 그리고 코드를 이해하기 쉽도록 하고자 덧붙여진다. Python에서는 주석이 해시 (숫자 표시) (#)로 시작된다.

 

Python에서는 독스트링 (docstrings)이 모듈, 클래스, 함수를 설명합니다.

 

def square_and_rooter(x):
    """Return the square root of self times self."""
    ...

 

보통 PEP 8#comments (the "파이썬 스타일 안내서(Python Style Guide)")의 주석 섹션대로 따라하면 된다. PEP 0257#specification (The Docstring Conventions Guide)에서 독스트링에 대한 더 많은 정보를 볼 수 있다.

 

코드 주석 처리하기

 

세따옴표를 코드의 주석 처리에 쓰지 않는 것을 추천한다. 좋은 습관이 아니다. grep처럼 라인 기반 커맨드 라인 도구는 주석 처리된 코드가 비활성화되었는지를 인식하지 못한다. 주석 처리할 모든 줄의 적당히 들여쓴 위치에다 해시를 붙이는 편이 좋다. 에디터에 이런 작업을 쉽게 해주는 기능이 있을 것이다. 주석 처리/해제하는 단축키를 배울 필요가 있다.

 

독스트링 (Docstrings)과 마법

 

어떤 도구는 단위 테스트 로직처럼 문서 이상의 동작을 시키기 위해 독스트링을 이용한다. 이런 도구들은 멋지지만, 절대 고장나지 않는다. "이렇게 동작할거야." 같은 역할을 할 뿐이다.

 

Sphinx 같은 툴은 당신의 독스트링을 reStructuredText로 파싱해서 HTML로 정확히 만들어준다. 이 방법은 프로젝트 문서에 예제 코드의 스니펫을 아주 간단히 집어넣을 수 있도록 해준다.

 

또한, Doctest는 Python 명령줄에서 입력된 것처럼 보이는 모든 임베디드 문서 문자열을 읽고 실행하며 명령어의 출력이 다음 줄의 텍스트와 일치하는지 확인한다. 이를 통해 개발자는 소스 코드와 함께 실제 예제 및 함수 사용을 포함할 수 있다. 부작용으로 코드가 테스트되고 작동하는지 확인한다.

 

def my_function(a, b):
    """
    >>> my_function(2, 3)
    6
    >>> my_function('a', 3)
    'aaa'
    """
    return a * b

 

독스트링 (Docstrings) 대 블록 주석

 

독스트링 (Docstrings)과 블록 주석은 서로 바꿔쓸 수 없다. 함수나 클래스에서 맨 앞줄의 주석 블록은 개발자의 메모로 쓰인다. 독스트링은 함수나 클래스의 동작 을 나타낸다.

 

# This function slows down program execution for some reason.
def square_and_rooter(x):
    """Returns the square root of self times self."""
    ...

 

블록 주석과 달리 문서 문자열은 파이썬 언어 자체에 내장되어 있다. 즉, Python의 강력한 내성 기능을 모두 사용하여 최적화된 코멘트와 비교하여 런타임에 문서 문자열에 액세스할 수 있다. 문서 문자열은 거의 모든 Python 객체에 대한 __doc_dunder 속성 및 내장 도움말() 함수에서 모두 액세스할 수 있다.

블록 코멘트는 보통 코드의 한 부분이나 알고리즘의 특정 작업을 설명하는 데 사용되지만, 문서 문자열은 특정 기능이 어떻게 사용될 수 있는지와 함수, 클래스 또는 모듈의 일반적인 목적을 설명하는 데 더 적합하다.

 

독스트링 (Docstrings) 작성

 

작성한 함수, 메서드, 클래스가 얼마나 복잡한지에 따라 다르겠지만 단 1줄의 독스트링이 가장 적절할 것이다. 다음은 흔히 쓰이면서도 아주 분명한 예시이다.

 

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

 

독스트링은 이해하기 쉬운 방법으로 함수를 설명해야 한다. 별 것도 아닌 함수나 클래스나 간단한 함수 구문 (예를 들면, add(a, b) -> result) 에서는 독스트링이 필요하지 않다. Python의 inspect 모듈이 이미 있기에 필요시 아주 빠르게 원하는 정보를 찾을 수 있고 소스 코드도 손쉽게 읽을 수 있기 때문이다.

 

하지만 더 크고 복잡한 프로젝트라면 함수 정보, 이게 뭘 하는지, 어떤 예외를 발생시키는지, 무엇을 반환하는지, 파라미터에 관한 연관 정보에 대하여 더 많이 설명하는 편이 좋은 경우도 많다.

 

더 자세한 코드 문서화를 위해 널리 사용되는 스타일은 NumPy 프로젝트에서 사용되는 스타일이며 종종 NumPy style 문서 문자열로 불린다. 이전 예제보다 더 많은 라인을 차지할 수 있지만, 개발자는 메서드, 함수 또는 클래스에 대한 훨씬 더 많은 정보를 포함할 수 있다.

 

def random_number_generator(arg1, arg2):
    """
    Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    int
        Description of return value

    """
    return 42

 

스핑크스에 sphinx.ext.napoleon 플러그인을 추가하면 이러한 스타일의 독스트링을 파싱하여 NumPy 스타일의 독스트링을 당신의 프로젝트에 집어넣기 쉽게 해준다.

 

결국, 문서 문자열을 작성할 때 어떤 스타일을 사용하는지는 중요하지 않다. 문서 문자열의 목적은 코드를 읽거나 변경해야 하는 모든 사용자를 위한 문서 역할을 하는 것이다. 정확하고, 이해할 수 있고, 관련 요점을 이해한다면, 그것은 그것이 하도록 설계된 일을 해냈다.

 

https://python-guide-kr.readthedocs.io/ko/latest/writing/documentation.html

문서화 — The Hitchhiker's Guide to Python