Python의 여러 줄 주석 문서 작성 스타일

docstring이란 무엇입니까

소프트웨어 엔지니어링에서 코딩은 실제로 문서 작성과 같은 매우 작은 부분을 차지합니다. 문서는 의사소통을 위한 도구입니다.
Python에서는 코드로 문서를 작성하는 것이 더 편리하고 유지 관리가 쉽고 직관적이며 일관성이 있는 문서입니다.
코드가 작성되고 문서가 공개되었습니다. 사실 마크다운도 비슷한 생각을 갖고 있는데, 텍스트를 작성하고 나면 조판도 완료된다.
PEP 0257에서 docstring의 정의를 살펴보세요.

docstring은
모듈, 함수, 클래스 또는 메서드 정의에서 첫 번째 문으로 나타나는 문자열 리터럴입니다. 🎜>해당 객체의 __doc__ 특수 속성이 됩니다.
간단히 말하면 모듈, 함수, 클래스 또는 메소드에 나타나는 첫 번째 명령문은 독스트링입니다. 자동으로 __doc__ 속성이 됩니다.

def foo():
  """ This is function foo"""

foo.__doc__'를 통해 액세스할 수 있습니다. 이것은 foo' 함수입니다.

다양한 독스트링 스타일:

Epytext

이것은 한때 javadoc과 유사한 인기 스타일이었습니다.

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

요즘 유행하는 스타일, reST 스타일, 스핑크스의 로열 형식이에요. 나는 또한 개인적으로 더 컴팩트한 이 스타일을 사용하는 것을 좋아합니다. Numpydoc(Numpy 스타일)

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

docstring 도구 타사 라이브러리 pyment

를 사용하여

사용 방법은 pyment를 사용하여 패치를 생성한 후 적용하는 것입니다.

"""
This is a groups style docs.

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

세부정보: https://github.com/dadadel/pyment

스핑크스의 autodoc을 사용하여 docstring에서 자동으로 api 문서를 생성합니다. 손으로 다시 작성해야 합니다

이미 코드에 docstring을 작성해 두었습니다. API 문서 작성 내용도 이와 비슷합니다. 먼저 하나씩 복사해야 합니까? 물론 그렇지 않습니다. 스핑크스에는 autodoc 기능이 있습니다.

먼저 conf.py 파일을 편집하세요. 1. 'sphinx.ext.autodoc' 확장자가 있어야 합니다. 2. 자동으로 문서를 생성해야 하는 모듈을 가져올 수 있는지 확인하세요. , 경로에 있습니다. 예를 들어 sys.path.insert(0, os.path.abspath('../..'))

그런 다음 첫 번째 파일

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

먼저 직접 작성할 필요 없이 docstring에서 관련 문서를 생성하려면 make html 명령을 입력하세요.

효과 보기:

Python의 여러 줄 주석 문서 작성 스타일과 관련된 더 많은 기사를 보려면 PHP 중국어 웹사이트를 주목하세요!