문서화
Python 패키지 개발하기
James Fulton
Climate informatics researcher
왜 문서화를 포함하나요?
- 사용자가 코드를 올바르게 쓰도록 돕습니다
- 각각 문서화
- 함수
- 클래스
- 클래스 메서드
import numpy as np
help(np.sum)
...
sum(a, axis=None, dtype=None, out=None)
주어진 축에 대해 배열 요소의 합을 계산합니다.
Parameters
----------
a : array_like
합칠 요소.
axis : None or int or tuple of ints, optional
합을 계산할 축(들).
기본값 axis=None이면 입력 배열의 모든
요소를 합칩니다.
...
왜 문서화를 포함하나요?
- 사용자가 코드를 올바르게 쓰도록 돕습니다
- 각각 문서화
- 함수
- 클래스
- 클래스 메서드
import numpy as np
help(np.array)
...
array(object, dtype=None, copy=True)
배열을 생성합니다.
Parameters
----------
object : array_like
배열 인터페이스를 노출하는 임의의 객체
또는 배열 ...
dtype : data-type, optional
배열의 원하는 데이터 타입.
copy : bool, optional
true(기본값)이면 객체를 복사합니다.
...
왜 문서화를 포함하나요?
- 사용자가 코드를 올바르게 쓰도록 돕습니다
- 각각 문서화
- 함수
- 클래스
- 클래스 메서드
import numpy as np
x = np.array([1,2,3,4])
help(x.mean)
...
mean(...) method of numpy.ndarray instance
a.mean(axis=None, dtype=None, out=None)
지정한 축을 따라 배열 요소의 평균을 반환합니다.
전체 문서는 `numpy.mean`을 참조하십시오.
...
함수 문서화
def count_words(filepath, words_list):""" ... """
함수 문서화
def count_words(filepath, words_list):"""이 단어들이 나타나는 총 횟수를 셉니다."""
함수 문서화
def count_words(filepath, words_list):"""이 단어들이 나타나는 총 횟수를 셉니다. 지정된 위치의 텍스트 파일에서 셉니다. """
함수 문서화
def count_words(filepath, words_list):"""이 단어들이 나타나는 총 횟수를 셉니다. 지정된 위치의 텍스트 파일에서 셉니다. [filepath와 words_list가 무엇인지 설명] [반환값] """
문서 스타일
Google 문서 스타일
"""요약 줄.
함수의 상세 설명.
Args:
arg1 (int): arg1 설명
arg2 (str): arg2 설명
NumPy 스타일
"""요약 줄.
함수의 상세 설명.
Parameters
----------
arg1 : int
arg1 설명 ...
Returns
----------
numpy.ndarray
reStructuredText 스타일
"""요약 줄.
함수의 상세 설명.
:param arg1: arg1 설명
:type arg1: int
:param arg2: arg2 설명
:type arg2: str
Epytext 스타일
"""요약 줄.
함수의 상세 설명.
@type arg1: int
@param arg1: arg1 설명
@type arg2: str
@param arg2: arg2 설명
NumPy 문서 스타일
다음과 같은 과학 파이썬 패키지에서 널리 사용됨
numpyscipypandassklearnmatplotlibdask- 등
NumPy 문서 스타일
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear') 지정한 축을 따라 데이터의 q번째 분위수를 계산합니다. 배열 요소의 q번째 분위수를 반환합니다.Parameters ----------a : array_like배열로 변환 가능한 입력 배열 또는 객체.
기타 타입 예: int, float, bool, str, dict, numpy.array 등
NumPy 문서 스타일
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Parameters
----------
...
axis : {int, tuple of int, None}
...
interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
- 필요하면 파라미터에 여러 타입을 나열
- 유효 값이 몇 개뿐이면 허용 값 목록 제시
NumPy 문서 스타일
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Returns
-------
percentile : scalar or ndarray
`q`가 단일 분위수이고 `axis=None`이면 결과는 스칼라입니다.
여러 분위수를 주면 결과의 첫 축이 분위수에 대응합니다...
...
NumPy 문서 스타일
기타 섹션
RaisesSee AlsoNotesReferencesExamples
1 https://numpydoc.readthedocs.io/en/latest/format.html
문서 템플릿과 스타일 변환
pyment로 독스트링을 생성할 수 있습니다- 터미널에서 실행
- 다음 중 임의의 문서 스타일 지원
- Numpydoc
- reST(= reStructuredText)
- Javadoc(= epytext)
- 문서 스타일 간 변환 가능
문서 템플릿과 스타일 변환
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
# 텍스트 파일 열기
...
return n
-w- 파일 덮어쓰기-o numpydoc- NumPy 스타일로 출력
문서 템플릿과 스타일 변환
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
"""
Parameters
----------
filepath :
words_list :
Returns
-------
type
"""
Google 스타일로 변환
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""이 단어들이 나타나는 총 횟수를 셉니다.
지정된 위치의 텍스트 파일에서 셉니다.
Parameters
----------
filepath : str
텍스트 파일 경로.
words_list : list of str
이 단어들의 총 등장 횟수를 셉니다.
Returns
-------
"""
Google 스타일로 변환
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""이 단어들이 나타나는 총 횟수를 셉니다.
지정된 위치의 텍스트 파일에서 셉니다.
Args:
filepath(str): 텍스트 파일 경로.
words_list(list of str): 이 단어들의 총 등장 횟수를 셉니다.
Returns:
"""
패키지, 서브패키지, 모듈 문서화
mysklearn/__init__.py
"""
파이썬용 선형회귀
============================
mysklearn은 파이썬에서 선형회귀를 구현하는
완전한 패키지입니다.
"""
mysklearn/preprocessing/__init__.py
"""
표준 전처리 작업을 위한 서브패키지.
"""
mysklearn/preprocessing/normalize.py
"""
데이터 정규화를 위한 모듈.
"""
연습해 봅시다!
Python 패키지 개발하기
