파이썬에서 Sphinx를 사용하여 문서화 작업을 시작하는 방법을 알려드릴게요! Sphinx는 주로 코드의 문서를 자동으로 생성하는 데 사용되며, Python 프로젝트의 문서를 작성할 때 매우 유용함.
다음은 Sphinx를 설정하고 사용하는 기본적인 단계입니다:
1. Sphinx 설치
먼저 Sphinx를 설치해야 함. 터미널이나 커맨드 라인에서 아래 명령어를 입력하면 됨.
! pip install sphinx2. 프로젝트 초기화
Sphinx를 사용하려면,
a. 프로젝트 생성
b. cd 명령어로 프로젝트 폴더로 이동
c. sphinx-quickstart 명령어를 실행하여 기본적인 설정 파일들을 생성함.
sphinx-quickstart이 명령어는 몇 가지 질문을 던짐. 기본값을 선택해도 되지만, 설정할 중요한 부분은 다음과 같았음.
- Root path for the documentation: 문서화할 폴더 경로.
- Separate source and build directories: source 폴더와 build 폴더를 분리할지 여부.
이렇게 하면 source 폴더와 build 폴더, 그리고 몇 가지 설정 파일들이 생성됩니다.
3. conf.py 설정
source 폴더에 생성된 conf.py 파일을 열어 문서화 설정을 변경할 수 있습니다. 특히 중요한 부분은:
- extensions: Sphinx는 다양한 확장 기능을 지원합니다. 예를 들어, Python 코드의 docstring을 추출하려면 autodoc 확장을 추가해야함.
# conf.py 파일에서
extensions = [
'sphinx.ext.autodoc', # 자동으로 docstring을 추출
'sphinx.ext.napoleon', # Google 스타일 docstring 지원
]- html_theme: 문서의 테마를 설정할 수 있음.
html_theme = 'alabaster'4. 문서화할 코드에 docstring 작성
Sphinx는 docstring을 기반으로 문서를 생성합니다. 코드에서 함수, 클래스 등에 docstring을 추가해야 했음.
예를 들어, 아래와 같이 함수에 docstring을 작성하면 됨.
# **Google** Docstring_Style_Type
def add(a, b):
"""
두 숫자의 합을 반환하는 함수
Args:
a (int): 첫 번째 숫자
b (int): 두 번째 숫자
Returns:
int: 두 숫자의 합
"""
return a + b# **NumPy** Docstring_Style_Type
def add(a, b):
"""
두 숫자의 합을 반환하는 함수
Parameters
----------
a : int
첫 번째 숫자
b : int
두 번째 숫자
Returns
-------
int
두 숫자의 합
"""
return a + b# **restructredTexted** Docstring_Style_Type
def add(a, b):
"""
두 숫자의 합을 반환하는 함수
:param a: 첫 번째 숫자
:type a: int
:param b: 두 번째 숫자
:type b: int
:return: 두 숫자의 합
:rtype: int
"""
return a + b
5. .rst 파일 작성
source 폴더에 있는 index.rst 파일을 열고, 여기에 문서의 목차나 내용을 작성함.
예를 들어, 자동으로 API 문서를 추가하려면 다음과 같이 작성해야함.
.. automodule:: your_module_name
:members:your_module_name 은 문서화하려는 Python 모듈 이름으로 바꾸면 됨.
6. 빌드 및 확인
아래 명령어를 cmd에서 실행해서 build 폴더에 HTML 파일을 생성함.
make html이 명령어를 실행하면, build/html 폴더에 HTML 형식의 문서가 생성되고, index.html 파일을 실행하면 브라우저에서 문서된 내용을 확인할 수 있음.
7. 추가 확장 기능 (옵션)
- autodoc: Python 코드의 docstring을 자동으로 추출하여 문서에 삽입할 수 있음.
- napoleon: Google 스타일과 NumPy 스타일의 docstring을 지원하는 확장 기능.
예시
# example.py
def greet(name):
"""
주어진 이름으로 인사를 합니다.
:param name: 이름 (문자열)
:return: 인사 메시지
"""
return f"Hello, {name}!"결론
오늘은 Python 프로젝트에서 Sphinx를 사용한 코드 문서화를 활용해보았음.
문서의 스타일, 확장 기능, 빌드 방법 등은 필요에 따라 자유롭게 수정할 수 있으니, 공식 Sphinx 문서를 참고하여 더 다양한 기능을 만나볼 수 있음.
(+추가) Docsting 종류
(상세내용은 접는 글에서 확인 가능함)
- Google 스타일: 일반적인 개발 프로젝트에서 많이 사용함. 간결하고 직관적이며, 빠르게 문서화할 수 있기 때문
- NumPy 스타일: 과학적, 데이터 분석, 머신러닝 프로젝트에서 사용함. 매개변수가 많거나 복잡한 함수를 명확하게 구분할 때
- reST 스타일: Sphinx와 잘 통합되어 큰 프로젝트나 문서화가 중요한 경우, Sphinx에서 제공하는 기본 스타일이라서 자동화된 코드 문서화에 특화된 스타일.
각 스타일은 사용되는 상황에 따라 적합성이 달라지므로, 프로젝트의 성격과 사용하려는 문서화 도구에 맞춰 스타일을 선택하는 것이 중요함.
주로 사용되는 곳: 일반적인 프로젝트에서 많이 사용됨.
- 팀 간 협업이 많고, 코드의 간결함과 직관성을 중요시하는 프로젝트에서 주로 사용됨.
- 웹 개발이나 스크립트 기반 프로젝트 등에서 널리 사용됨.
장점:
- 간결하고 읽기 쉬움: Google 스타일은 기본적으로 간결하며, 항목 간 구분이 명확해 쉽게 읽을 수 있음.
- 대부분의 사람에게 친숙함: Google 스타일은 직관적이고 친숙해 많은 개발자들이 쉽게 이해하고 사용할 수 있음.
- 자동화 도구와의 호환성: 많은 자동화 도구나 문서화 툴에서 Google 스타일을 기본적으로 지원함.
- 간결하고 직관적이라, 개발자가 빠르게 문서를 작성할 수 있음.
- 특히 빠른 문서화가 필요한 경우 유용.
- Google 스타일은 매우 친숙하고 쉽게 이해할 수 있어 대부분의 개발자가 편하게 사용할 수 있음.
단점:
- 세부적인 정보 부족: Google 스타일은 항목을 명시하는 데 충분한 공간을 제공하지만, NumPy 스타일이나 reST 스타일보다 추가적인 세부사항을 담기엔 다소 부족할 수 있음.
- 비표준화된 형식: Google 스타일은 그 자체로 널리 사용되지만, Python 커뮤니티의 표준이라고 할 수는 없음.
예시: Google, Dropbox, Airbnb 등 다양한 오픈소스 프로젝트에서 사용됨.
NumPy
주로 사용되는 곳: 과학적, 데이터 분석, 머신러닝 프로젝트에서 많이 사용됨.
- 복잡한 수학적 함수나 데이터 분석 도구에서는 매개변수와 반환값을 명확하게 정의하는 것이 중요하기 때문에 NumPy 스타일이 자주 사용됨.
- Pandas, SciPy, NumPy 등과 같은 과학적 라이브러리에서 표준으로 사용됨.
장점:
- 구조가 명확함: Parameters, Returns, Raises 등으로 나누어져 있어 문서가 매우 구조적이고 명확함.
- 복잡한 함수나 클래스에 유용: 함수가 복잡하거나 매개변수가 많을 때 NumPy 스타일이 유리함. 각 매개변수와 반환값을 명확하게 구분하여 설명할 수 있음.
- 과학 및 데이터 분석 분야에서 널리 사용됨: NumPy 스타일은 특히 데이터 분석, 과학 계산, 머신러닝 등에서 많이 사용됨.
- 매개변수와 반환값을 명확하게 정의하고, 구조적으로 잘 나누어져 있어 복잡한 함수에서 유리함.
- 과학적 커뮤니티에서 널리 사용되어, 해당 분야에서는 다른 사람들과의 협업 시 편리함.
단점:
- 길어지고 반복적임: 많은 함수나 클래스에서 Parameters와 Returns를 반복적으로 작성해야 하기 때문에 문서가 길어질 수 있음.
- 구조가 다소 복잡: 함수가 간단할 경우에는 다소 과도한 형식일 수 있음
예시: Pandas, NumPy, SciPy 등과 같은 과학적 및 데이터 분석 라이브러리에서 주로 사용됨.
restructuredText (reST)
주로 사용되는 곳: Sphinx 기반 문서화가 필요한 프로젝트에서 주로 사용됨.
- Sphinx로 자동화된 문서화를 필요로 하는 프로젝트에서 많이 사용됨.
- autodoc을 사용하여 Python 코드를 자동으로 문서화할 때 기본적으로 reST 스타일을 사용함.
장점:
- Sphinx와의 호환성: reST 스타일은 Sphinx에서 기본적으로 지원되며, 매우 잘 통합됨. Sphinx 문서화 시스템을 사용하는 경우 가장 자연스러운 선택이 될 수 있음.
- 유연성: :param, :type, :return, :rtype 등 다양한 디렉티브를 통해 매개변수와 반환값을 명확하게 설명할 수 있음. 함수에 대한 세부 정보 제공이 용이함.
- 전통적인 Python 스타일: reST는 Python 커뮤니티에서 오랜 기간 사용되어 온 표준 형식 중 하나로, autodoc과 같은 도구와 잘 호환됨.
- Sphinx와 완벽하게 호환되어, 대규모 프로젝트에서 자동 문서화 작업을 쉽게 처리할 수 있음.
- 복잡한 문서를 생성할 때 유리하고, :param, :type, :return 등의 디렉티브를 사용하여 매우 구체적이고 상세한 문서를 작성할 수 있음.
단점:
- 다소 장황할 수 있음: 다른 스타일들보다 문법적으로 길고 다소 복잡할 수 있음. 특히 간단한 함수나 클래스에는 지나치게 많은 디렉티브를 사용하는 경우가 발생할 수 있음.
- readability: :param과 :type 등을 사용하는 방식은 문서가 다소 기계적으로 보일 수 있으며, 일부 개발자들에게는 읽기에 불편할 수 있음.
예시: Django, Flask와 같은 대규모 프로젝트에서는 Sphinx 문서화 시스템을 많이 사용하며, 이를 위해 reST 스타일을 채택함.
차이점 요약
| 스타일 | NumPy | restructuredText(reST) | |
| 구조 | 간단하고 직관적 | 명확하고 구조적 | 유연하고 다소 복잡 |
| 주요 사용 | 간단한 함수나 클래스 | 과학/데이터 분석 분야 | Sphinx 문서화 시스템과의 호환성 |
| 문서화 편의성 | 빠르고 간편 | 구체적이고 명확 | 많은 디렉티브를 요구 |
| 유연성 | 낮음 | 높음 | 매우 높음 |
| 호환성 | 대부분의 자동화 도구와 호환 | 과학적 도구들에서 널리 사용 | Sphinx와의 매우 좋은 호환성 |
| 주요 단점 | 세부사항 부족 | 길고 반복적 | 다소 복잡하고 기계적 |
결론
- Google 스타일: 일반적인 개발 프로젝트에서 많이 사용함. 간결하고 직관적이며, 빠르게 문서화할 수 있음.
- NumPy 스타일: 과학적, 데이터 분석, 머신러닝 프로젝트에서 사용. 매개변수가 많거나 복잡한 함수를 명확하게 구분할 수 있음.
- reST 스타일: Sphinx와 잘 통합되어 큰 프로젝트나 문서화가 중요한 경우, Sphinx에서 제공하는 기본 스타일이라서 자동화된 코드 문서화에 특화된 스타일.
Google 스타일: 일반적인 개발 프로젝트에서 많이 사용. 간결/직관적이며, 빠르게 문서화할 수 있기 때문
NumPy 스타일: 과학적, 데이터 분석, 머신러닝 프로젝트에서 사용. 매개변수가 많거나 복잡한 함수를 명확하게 구분할 때
reST 스타일: Sphinx와 잘 통합되어 큰 프로젝트나 문서화가 중요한 경우, 특히 Sphinx 문서화 시스템을 사용할 때
각 스타일은 사용되는 상황에 따라 적합성이 달라지므로, 프로젝트의 성격과 사용하려는 문서화 도구에 맞춰 스타일을 선택하는 것이 중요함.
Tip) PyCharm에서 docstring 자동 생성 설정해서 """ 혹은 '''을 입력하면 코드 문서화를 빠르게 작성할 수 있음.
'기타 (Other)' 카테고리의 다른 글
| [python] 타입힌트: 공부용 (1) | 2025.02.17 |
|---|---|
| [python] PyCharm에서 docstring 자동 생성 설정 (0) | 2025.02.12 |
| [python] GoogleTranslator 번역 (0) | 2025.02.11 |
| [python] FastAPI (0) | 2025.02.11 |
| [Github] readme.md: 파일 트리 (1) | 2025.02.11 |