python - style - 표준 파이썬 docstring 형식은 무엇입니까?




python docstring to documentation (6)

형식

파이썬 문서 문자열은 다른 게시물에서 보여준 여러 형식으로 작성 될 수 있습니다. 그러나 기본 Sphinx docstring 형식은 언급되지 않았으며 reStructuredText (reST)를 기반으로합니다. 해당 튜 토의 주요 형식에 대한 정보를 얻을 수 있습니다.

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

다음은 문서화 문자열에 사용되는 주요 형식입니다.

- Epytext

역사적으로 스타일과 같은 javadoc 이 널리 보급되었으므로 문서를 생성하기 위해 Epydoc ( Epytext 형식이라고 함)의 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 에서 사용하는 reStructuredText (reST) 형식입니다. 참고 : JetBrains PyCharm (메소드 정의 및 히트 입력 후 트리플 인용 부호 입력)에서 기본적으로 사용됩니다. 또한 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은 자주 사용되는 format 을 가지고 있습니다. 그것은 또한 스핑크스 (즉, 나폴레옹 플러그인을 사용)에 의해 해석 될 수 있습니다.

예:

"""
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
"""

변환 / 생성 중

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

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

파이썬에서 docstring을 작성하는 몇 가지 스타일을 보았습니다. 공식 또는 "합의 된"스타일이 있습니까?


Docstring 컨벤션은 PEP-257 있으며 PEP-8보다 훨씬 자세히 나와 있습니다.

그러나 문서 문자열은 다른 코드 영역보다 훨씬 개인적인 것처럼 보입니다. 다른 프로젝트는 그들 만의 표준을 가질 것입니다.

필자는 함수를 사용하는 방법과 매우 빠르게 수행하는 것을 보여주기 때문에 docstring을 항상 포함하는 경향이 있습니다.

문자열의 길이에 관계없이 일관성있게 유지하는 것을 선호합니다. 들여 쓰기와 간격이 일관성이있을 때 코드를 작성하는 방법을 좋아합니다. 즉, 다음을 사용합니다.

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

위에:

def sq(n):
    """Returns the square of n."""
    return n * n

그리고 더 긴 docstrings의 첫 번째 줄에 주석을 남기려는 경향이 있습니다.

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

의미하는 것은 이런 식으로 시작하는 문서 문자열이 지저분하다는 것입니다.

def sq(n):
    """Return the squared result. 
    ...

그것은 파이썬입니다. 뭐든지 간다 . 문서게시 하는 방법을 고려하십시오. Docstring은 소스 코드의 독자를 제외하고 보이지 않습니다.

사람들은 웹에서 문서를 검색하고 검색하는 것을 정말로 좋아합니다. 이를 달성하려면 문서 도구 인 Sphinx 사용하십시오. Python 프로젝트를 문서화하기위한 사실상의 표준입니다. 제품이 아름답습니다 - https://python-guide.readthedocs.org/en/latest/ 에서보세요. 웹 사이트 독서 문서 는 무료로 문서 를 호스팅합니다.



Google 스타일 가이드 에는 뛰어난 Python 스타일 가이드가 포함되어 있습니다. 여기에는 PEP-257보다 나은 지침을 제공하는 읽을 수있는 docstring 구문에 대한 규칙 이 포함되어 있습니다. 예 :

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

스핑크스 문서 튜토리얼에 설명 된대로 인수에 유형 정보를 포함하도록 이것을 확장하고 싶다. 예 :

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

appumply 아무도 그것을 언급 : Numpy Docstring 표준을 사용할 수 있습니다. 그것은 과학 공동체에서 널리 사용됩니다.

구글 스타일의 문서 문자열 (@Nathan의 답안에서 권장)을 파싱하기위한 Napolean sphinx 확장은 또한 Numpy 스타일의 문서화 문자열을 지원하며 두 가지를 모두 comparison 봤다.

그리고 그것이 어떻게 생겼는지에 대한 아이디어를주는 마지막 예 :

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

    Extended description of function.

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

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True






docstring