Sphinx 란?
Python documentation 을 위한 오픈소스 프로젝트 입니다. Java Doc 처럼 파일, 클래스, 기능별로 문서화할 수 있으며, comment를 자동 인식하여 기본적으로 html 페이지를 생성합니다.
Sphinx에서는 comment를 무조건 다 인식할 수 있는게 아니라 인식할 수 있는 docstring 스타일이 존재합니다. 기본적으로 reStructuredText (rst) 포맷을 주로 사용하지만 Google 스타일도 있기 때문에, 스타일의 차이점과 그에 맞는 설정 방법을 설명 드리도록 하겠습니다.
docstring 스타일
기본적으로 주석은 """ 을 사용하며, docstring의 대상은 모듈, 클래스, 함수(메소드) 세 가지입니다.
아래 sum( ) 함수를 예로 들어보겠습니다. 인자에 타입 체크는 Python 3부터 진행된 것으로 옵션으로 표시할 수 있습니다.
reStructuredText
더 자세한 예제는 https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html 참조
def sum(arg1: int, arg2: int) -> int:
"""
This is sum function.
:param int arg1: Description of arg1.
:param int arg2: Description of arg2.
:return: Description of return value.
:rtype: int
:example:
>>> a=1
>>> b=2
>>> sum(a, b)
3
"""
return a + b> param 섹션
인자의 이름, 데이터형, 인자의 설명을 기재합니다.
:param 타입 인수명: 인수의 설명> return 섹션
return문을 사용한 함수의 리턴 값을 기재합니다.
:return: 리턴 값에 대한 설명> rtype 섹션
return값에 대한 데이터형을 기재합니다.
:rtype: 데이터형> example 섹션
본 함수에 대한 사용법을 기재합니다.
:example:
>>> a = 1
>>> b = 2
>>> sum(a, b)
3
Google-style
def sum(arg1: int, arg2: int) -> int:
"""
This is sum function.
Args:
arg1 (int): Description of arg1.
arg2 (int): Description of arg2.
Returns:
int: Description of return value
Examples:
>>> a=1
>>> b=2
>>> sum(a, b)
3
"""
return a + b> Args 섹션
인자의 이름, 데이터형, 인자의 설명을 기재합니다.
- optional 한 경우, 데이터형 뒤에 "optional" 로 추가하면 됩니다.
Args:
인자명 (인자의 데이터형): 인자 설명
인자명 (인자의 데이터형, optional): 인자 설명> Returns 섹션
return문을 사용한 함수의 리턴 값을 기재합니다.
reStructuredText와는 달리 rtype을 포함합니다.
Returns:
리턴 값의 데이터형: 리턴 값의 설명
> Examples 섹션
Examples:
함수의 사용법 기재
>>> a = 1
>>> b = 2
>>> sum(a, b)
3
Sphinx 설치
pip install sphinxSphinx를 설치하면 파일들이 자동 생성되는데 프로젝트 root path 에 들어가면 혼잡하므로 docs
라는 디렉토리를 생성하고 해당 디렉토리에서 진행합니다.
mkdir docs
cd docssphinx-quickstart # Sphinx 설치Welcome to the Sphinx 4.4.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]
The project name will occur in several places in the built documentation.
> Project name:
> Author name(s):
> Project release []:
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:
Creating file {PROJECT_PATH}/docs/source/conf.py.
Creating file {PROJECT_PATH}/docs/source/index.rst.
Creating file {PROJECT_PATH}/docs/Makefile.
Creating file {PROJECT_PATH}/docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file {PROJECT_PATH}\docs\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.> Separate source and build directories : source 디렉토리와 build 디렉토리 분리 여부
- 문서화할게 많으면 source 디렉토리와 build 디렉토리를 분리하는게 좋음 (y)
> Project name : 문서에 출력될 프로젝트 명
> Author name(s) : 저자
> Project release: 프로젝트 버전 (시작인 경우, 1.0)
> Project language: Sphinx 에서 자동 생성되는 문서가 어떤 언어로 작성될지 선택
- 디폴트가 영어 (영어로 진행할거면 그냥 Enter)
이렇게 docs 경로에 기본적인 파일들이 생성되었습니다.
다음 포스팅에선 Google-style 의 docstring 을 파싱할 수 있도록 conf.py 를 수정하고, index.rst 를 수정하는 방법에 대해 설명하도록 하겠습니다.
'Study > Development' 카테고리의 다른 글
| Python 3 설치 및 가상환경 구축 (0) | 2022.03.18 |
|---|---|
| Javadoc 생성 시 한글 깨짐, UTF-8 사용하기 (0) | 2014.08.06 |
