표준 파이썬 문서 문자열 형식에 대해서

질문 : 표준 Python 독 스트링 형식은 무엇입니까?

---

파이썬으로 독 스트링을 작성하는 몇 가지 다른 스타일을 보았습니다. 공식적인 또는 "합의 된"스타일이 있습니까?

답변

---

형식

파이썬 독 스트링은 다른 포스트에서 보여준 것처럼 여러 형식으로 작성할 수 있습니다. 그러나 기본 Sphinx 독 스트링 형식은 언급되지 않았으며 reStructuredText (reST)를 기반으로합니다. 이 블로그 게시물 에서 주요 형식에 대한 정보를 얻을 수 있습니다.

reST는 PEP 287에서 권장합니다.

독 스트링에 사용되는 주요 형식은 다음과 같습니다.

- 서사시

역사적으로 javadoc 과 같은 스타일이 널리 퍼져 있었기 때문에 Epydoc Epytext 형식이라고 함)의 기반으로 문서를 생성했습니다.

예:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

 

- reST

요즘에는 문서를 생성하기 위해 Sphinx 에서 사용하는 reST ( reStructuredText) 형식이 더 널리 사용되는 형식입니다. 참고 : JetBrains PyCharm에서 기본적으로 사용됩니다 (메서드를 정의한 후 세 개의 따옴표를 입력하고 Enter 키를 누르십시오). 기본적으로 Pyment의 출력 형식으로도 사용됩니다.

예:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

 

- Google

Google에는 자주 사용되는 자체 형식이 있습니다. 또한 Sphinx에서 해석 할 수도 있습니다 (예 : Napoleon 플러그인 사용 ).

예:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

더 많은 예

- Numpydoc

Numpy는 Google 형식을 기반으로하고 Sphinx에서 사용할 수있는 자체 numpydoc 을 따르는 것이 좋습니다.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Converting/Generating

Pyment와 같은 도구를 사용하여 아직 문서화되지 않은 Python 프로젝트에 대한 독 스트링 을 자동으로 생성하거나 기존 독 스트링 (여러 형식을 혼합 할 수 있음)을 한 형식에서 다른 형식으로 변환 할 수 있습니다.

참고 : 예제는 Pyment 문서 에서 가져온 것입니다.

출처 : https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format