Sphinx Docstring 모범 사례

Sphinx에서 사용하는 Docstrings가 어떻게 생겼는지 간단히 설명하고 싶습니다. 생성된 Sphinx 웹 페이지에 제대로 표시되는 독스트링을 만드는 방법과 표준화된 방식으로 함수에 대한 최대한의 정보를 전달하는 방법을 아는 것은 편리합니다.

파이썬에서 함수, 클래스, 메서드, 심지어 전체 모듈은 바로 아래에 삼중 따옴표로 묶인 문자열을 가질 수 있습니다. 일반적으로 한 줄에 상수를 단독으로 넣으면 효과가 없고 그냥 무시됩니다. 그러나 이러한 Python 구성 중 하나 바로 아래에 있는 삼중 따옴표 문자열은 문서처럼 취급되기 때문에 특별합니다. help() 콘솔에 표시되는 외부 도구와 Sphinx와 같은 문서 생성기에 의해 처리됩니다.

독스트링은 PEP 257 에 정의되어 있습니다. 독스트링을 구성할 때 작은 따옴표 대신 큰 따옴표를 사용하는 것이 좋습니다. 독스트링은 다음과 같이 한 줄에 올 수 있습니다.

def foo():
   """This is a one-line summary of foo()"""
   # function contents here

또는 요약 및 설명이 있는 여러 줄 독스트링으로:

def foo():
   """This is a one-line summary of foo()

   This is a longer description of what foo()
   does that can span several lines.
   """
   # function contents here

PEP 257은 독스트링의 모양을 정의하지만 독스트링에서 함수, 특히 매개변수, 반환 값 및 예외를 정의하는 정확한 형식은 정의하지 않습니다. 그것은 PEP 287에 포함되어 있습니다.

reStructuredText란?

계속하기 전에 reStructuredText가 무엇인지 알아야 합니다. 풍부한 형식의 텍스트를 입력하기 위해 개발된 Python 커뮤니티이므로 문서에만 국한되지 않는 마크업 언어입니다. Markdown과 구문이 비슷하지만 몇 가지 주요 차이점이 있습니다.

중첩된 번호 매기기 목록이 지원됩니다.

- A bullet list item
- Second item

  - A sub item

- Spacing between items separates list items

* Different bullet symbols create separate lists

- Third item

1) An enumerated list item

2) Second item

   a) Sub item that goes on at length and thus needs
      to be wrapped. Note the indentation that must
      match the beginning of the text, not the 
      enumerator.

      i) List items can even include

         paragraph breaks.

3) Third item

#) Another enumerated list item

#) Second item

이미지는 대괄호 대신 .. image:: 한정자를 사용합니다... image:: /path/to/image.jpg

마찬가지로 링크에는 두 개의 점이 있고 그 뒤에 공백, 링크 이름 및 URL이 있습니다... _Wikipedia: https://www.wikipedia.org/

이름이 없는 링크는 시작 부분에 두 개의 밑줄이 있습니다.__ https://www.python.org/

마지막으로 블록 따옴표는 들여쓰고 두 개의 대시 뒤에 작성자 이름이 옵니다.

This is an ordinary paragraph, introducing a block quote.

    "It is my business to know things.  That is my trade."

    -- Sherlock Holmes

reStructuredText의 스핑크스 독스트링 규칙

reStructuredText의 유연성으로 무장하면 문서를 생성하기 위해 Python 및 Python 기반 모듈에서 사용하는 Docutils에서 구현되기 때문에 Python이 특별히 볼 수 있는 docstring의 몇 가지 추가 지시문이 가능합니다.

여기에 나열할 5개의 docstring reStructuredText 지시문이 있습니다. 이러한 지시문은 Sphinx 문서 생성기에 의해 인식됩니다.

:param: : 이름, 용도, 기본값과 함께 함수 매개변수를 나타냅니다.:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]

:type: : 매개변수의 유형을 나타내며 연관된 :param: 지시문 바로 아래에 있어야 합니다. 또한 매개변수가 선택 사항인지 여부를 나타낼 수 있습니다. 매개변수가 필수임을 나타내려면 , optional 부분을 제외하기만 하면 됩니다.:type [ParamName]: [ParamType], optional

:raises: : 예외가 발생했음을 나타내며 해당 유형 및 설명입니다.:raises [ErrorType]: [ErrorDescription]

:return: : 함수에서 반환되는 내용을 나타낼 수 있습니다.:return: [ReturnDescription]

:rtype: 반환 값의 유형을 나타냅니다.:rtype: [ReturnType]

독스트링의 각 지시문 행은 110자 이하로 확장되는 것이 관례입니다. 지시문이 여러 줄에 오버플로되면 첫 번째 줄의 시작 부분을 기준으로 4칸 들여쓰기됩니다.

그리고 우리는 끝났어

이 게시물에 오류가 있으면 알려주시면 수정할 수 있도록 하겠습니다.


출처:
https://en.wikipedia.org/wiki/ReStructuredText
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html