본문 바로가기
Study/Development

Python 문서화 (1) - Sphinx 설치 및 docstring 스타일 선택

by SeulKom 2022. 3. 22.

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 sphinx

Sphinx를 설치하면 파일들이 자동 생성되는데 프로젝트 root path 에 들어가면 혼잡하므로 docs

라는 디렉토리를 생성하고 해당 디렉토리에서 진행합니다.

 

mkdir docs
cd docs
sphinx-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 디렉토리 구성

이렇게 docs 경로에 기본적인 파일들이 생성되었습니다.

 

다음 포스팅에선 Google-style 의 docstring 을 파싱할 수 있도록 conf.py 를 수정하고, index.rst 를 수정하는 방법에 대해 설명하도록 하겠습니다.

'Study > Development' 카테고리의 다른 글

Python 3 설치 및 가상환경 구축  (0) 2022.03.18
Javadoc 생성 시 한글 깨짐, UTF-8 사용하기  (0) 2014.08.06