체재

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

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

docstring에 사용되는 주요 형식은 다음과 같습니다.

-Epytext

역사적으로 스타일과 같은 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
"""

– 쉬다

요즘 가장 널리 사용되는 형식은 문서를 생성하기 위해 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에는 자주 사용되는 자체 형식 이 있습니다. 또한 스핑크스 (예 : 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.
"""

심지어 더 많은 예제

-누 피독

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 프로젝트로 자동 생성하거나 기존의 문서화 문자열 (여러 형식을 혼합 할 수 있음)을 형식에서 다른 형식으로 변환 할 수 있습니다.

참고 : 예제는 Pyment 문서 에서 가져 왔습니다.

답변

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

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

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

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

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