파이썬 패키지를 배포할 때 문서화는 매우 중요합니다. 문서화를 통해 사용자들은 패키지의 기능과 사용법을 쉽게 이해할 수 있고, 개발자들은 프로젝트를 유지보수하고 확장하는 데 도움을 받을 수 있습니다. 이번 블로그 포스트에서는 파이썬 패키지를 문서화하는 방법에 대해 알아보겠습니다.
1. docstring 작성하기
문서화의 첫 번째 단계는 코드에 docstring을 작성하는 것입니다. docstring은 함수, 클래스, 모듈 등의 코드 블록 앞에 작성되는 문자열입니다. 다른 개발자들이 코드를 이해하고 사용할 수 있도록 코드의 목적, 매개변수, 반환값 등을 설명하는 역할을 합니다.
아래는 add 함수의 예시입니다.
def add(a, b):
"""
두 개의 숫자를 더하는 함수입니다.
Parameters:
a (int): 첫 번째 숫자
b (int): 두 번째 숫자
Returns:
int: 두 숫자의 합
"""
return a + b
2. Sphinx로 문서 생성하기
docstring을 작성한 후에는 Sphinx를 사용하여 문서를 생성할 수 있습니다. Sphinx는 파이썬 코드의 문서를 작성하기 위한 도구로 널리 사용되고 있습니다.
먼저, Sphinx를 설치합니다.
pip install sphinx
다음으로, 프로젝트의 루트 디렉토리에서 다음 명령을 실행하여 Sphinx 프로젝트를 생성합니다.
sphinx-quickstart
이후에는 Sphinx의 설정 파일인 conf.py를 수정하여 문서의 설정을 진행합니다. 여기서는 최소한의 설정만을 다루도록 하겠습니다.
# conf.py
# ...
# 프로젝트의 루트 디렉토리
project = 'mypackage'
# 파이썬 모듈의 경로
import os
import sys
sys.path.insert(0, os.path.abspath('../'))
# 모든 모듈의 docstring을 수집하기 위해 autodoc 플러그인을 활성화
extensions = [
'sphinx.ext.autodoc'
]
# 경고 메시지 출력 여부 설정
warnings = []
이제, 문서에 포함할 모듈의 docstring을 수집하기 위해 다음 명령을 실행합니다.
sphinx-apidoc -o source/ ../mypackage
마지막으로, 다음 명령을 실행하여 HTML 문서를 생성합니다.
make html
이제 build/html 디렉토리에 생성된 HTML 문서를 확인할 수 있습니다.
3. 문서 확장 방법
Sphinx를 사용하여 문서를 생성하는 것 외에도, 여러 가지 확장기능을 사용하여 더욱 풍부하고 유용한 문서를 작성할 수 있습니다. 예를 들어, 다음과 같은 확장기능이 있습니다.
sphinx.ext.autodoc: 모든 모듈의 자동 문서 생성sphinx.ext.intersphinx: 다른 프로젝트의 문서와 링크sphinxcontrib.napoleon: Google 스타일의 docstring 사용sphinx_rtd_theme: Read the Docs 테마 사용
추가적인 확장기능의 사용법은 Sphinx 공식 문서를 참고하시기 바랍니다.