[python] Google 스타일의 Python Docstring 입문

들어가기에 앞서

---

 이 포스팅은 Google 스타일 형식으로 Python Docstring의 작성법에 대해서 필요한 최저한의 내용을 설명한다. 앞으로 Python Docstring을 기억하고자하는 엔지니어에게 도움이 된다면 좋겠다.

 

Python Docstring이란?

 Python에 있어서 클래스나 메소드(함수)에 대한 설명을 기재한 주석이다. Docstring은 __doc__이라는 변수에 저장되어 있다. 

아래는 print 메소드의 Docstring을 표시되도록 한 것이다.

>>> print(print.__doc__)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

 만든 클래스나 메소드에 Docstirng을 기재해두면 IDE상에 보충 정보로써 표시되도록 하거나 Sphinx를 이용하여 소스 코드의 사양서를 자동 작성되도록 할 수 있다.

 

Sphinx란?

 Sphinx는 reStructuredText라는 형식으로 기재된 텍스트를 HTML, PDF나 epub등의 다양한 형식에 변환할 수 있는 OSS의 문서 생성 툴이다. 

 Python 공식 문서는 Sphinx를 사용하여 작성되었다. Sphinx을 사용하여, Python의 소스 코드에서 부터 Python Docstring 주서문을 추출하여 소스 코드 사양서를 자동 작성하는 것이 가능하다. 

 Sphinx을 이용한 Docstring의 활용방법은 이 포스팅을 참고하길 바란다.

 

Google 스타일

Google이 제창한 Docstring의 기법의 하나로 Docstring의 기법에는 reStructuredText스타일, Numpy 스타일, Google 스타일 3개가 있다.

이번 포스팅에서는 Google 스타일에 대해서 설명하도록 하겠다.

 

Google 스타일의 Python Docstirng

---

Sphinx의 샘플 코드

Sphinx의 HP부터 Google스타일 형식으로 기재된 샘플 코드를 열람할 수 있다.

- Example Google Style Python Docstrings

위의 소스코드를 Sphinx을 이용해 html으로 변환한 것은 아래의 링크에서 확인할 수 있다.

- https://11ohina017.github.io/google_style_code/index.html

 

일본어 샘플 코드

방금의 샘플 코드에서 요점만을 발췌한 일본어로 된 샘플 코드와 소스코드를 Sphinx를 이용해 html으로 변환한 것은 이 링크에서 확인할 수 있다.

#!/usr/bin/python
# -*- coding: utf-8 -*-
"""모듈 설명 제목

     * 소스코드의 첫 시작부분에 기재할 것
     * import보다 앞서서 기재할 것

Todo:
   TODO리스트를 기재
    * conf.py의``sphinx.ext.todo`` 를 적용하지 않으면 사용할 수 없다.
    * conf.py의``todo_include_todos = True``로 하지 않으면 보이지 않는다.

"""

import json
import inspect

class testClass() :
    """클래스 설명 제목

     클래스에 대한 설명문

    Attributes:
        속성의 이름 (속성의 데이터형): 속성의 설명
       	속성의 이름 (:obj:`속성의 데이터형`): 속성의 설명.

    """

    def print_test(self, param1, param2) :
        """함수 설명 제목

         함수에 대한 설명문

        Args:
            인수의 이름 (인수의 데이터형): 인수의 설명
            인수의 이름 (:obj:`인수의 데이터형`, optional): 인수의 설명

        Returns:
           리턴 값의 데이터형: 리턴 값의 설명(예 : True 라면 성공, False이라면 실패.)

        Raises:
            예외명: 예외의 설명 (예 : 인수가 지정되지 않은 경우에 발생 )

        Yields:
           리턴값의 데이터형: 리턴값에 대한 설명

        Examples:

            함수의 사용법 기재

            >>> print_test ("test", "message")
               test message

        Note:
            주의항목 등을 기재

        """
        print("%s %s" % (param1, param2) )

if __name__ == '__main__':

    test_object = testClass()
    test_object.print_test("test", "message")

 

기본적인 주석 작성법

- 주석을 복수행의 주석 블록 「"""」으로 감싼다.

- 「"""」의 오른쪽에는 제목(타이틀)을 기재한다.

- Docstirng의 대상이 되는 것은 모듈, 클래스, 함수(메소드) 세 가지이다.

모듈의 기재 방법

소스 코드의 맨 앞에 소스 코드의 전체, 즉 모듈의 설명을 작성한다.

주의점은 주석문을 소스 코드의 시작점의 제일 위에 기재할 필요가 있다는 것이다.

※ import 보다 앞에 기재해야할 필요가 있다.

#!/usr/bin/python
# -*- coding: utf-8 -*-
"""모듈 설명 제목

   모듈의 설명

"""

클래스의 기재 방법

아래와 같이 클래스 정의문 바로 아래 행에 작성한다.

class testClass() :
    """클래스 설명 제목

     클래스에 대한 설명문

    """

함수(메소드)의 기재 방법

아래와 같이 함수 정의 아래 행에 작성한다.

def print_test(self, param1, param2) :

    """함수 설명 제목

     함수에 대한 설명문
    """

 

섹션에 대한 설명

Google 스타일에는 Attributes, Args, Returns, Yieds, Raises, Examples, Note, Todo라는 용도 별로 정의된 섹션이 있다.

Attributes 섹션

클래스 속성의 데이터형, 이름 등 클래스의 속성 설명을 작성한다.

Attributes:
    속성명 (속성의 데이터형): 속성의 설명
    속성명 (:obj:`속성의 데이터형`): 속성의 설명

Args 섹션

인수의 이름, 데이터형, optional(생략 가능)인가 아닌가, 인수의 설명을 기재하는 섹션이다.

- 인스턴스를 표시하는 self는 Args섹션에 기재하지 않고 생략한다.

- 생략가능한 인수는 아래와 같이 optional을 기재한다.

- Sphinx를 이용해 html파일로 변환하면 Args > Paramters로 변환된다.

Args:
    인수명 (인수의 데이터형): 인수의 설명
    인수명 (:obj:`인수의 데이터형`, optional): 인수의 설명

Returns 섹션

return문을 사용한 함수의 리턴값을 기재하는 섹션이다.

Returns:
   리턴값의 데이터형: 리턴값의 설명(예 : True 이라면 설명, False 이라면 실패)

Yields 섹션

yeild문을 사용한 함수의 리턴값을 기재하는 섹션이다.

Yields:
   리턴값의 데이터형: 리턴값에 대한 설명

Raisee 섹션

예외 처리에 대한 설명을 기재하는 섹션이다.

Raises:
    예외명: 예외의 설명 (예 : 인수가 지정되지 않은 경우 발생)

Examples 섹션

함수, 클래스의 실행예에 대해서 기재하는 섹션이다.

Examples:
    함수의 사용법에 대해 작성
    >>> print_test ("test", "message")
       test message

- Examples이 아닌, Example도 가능하다.

- 클래스, 메소드 이외의 장소에 사용하는 경우에는 아래와 같이 "::"로 코드 블록을 만들 필요가 있다.

- "\"는 에스케이 문자이므로, 코드 블록 안에 "\"로 표시하고 싶은 경우 "\\"로 기재한다.

Example:
    함수의 사용법에 대해 기재

    ::

        $ python main.py \\
            "arg1" \\
            "args2" \\

Note 섹션

주석에 대해 작성하는 섹션.

예를 들어, '이 코드는 Python2버전에서는 동작하지 않습니다'와 같은 주의항목을 기재하는데 사용한다.

Note:
   주의항목 등을 기재

Todo 섹션

Todo 리스트를 기재하는 위한 섹션.

제작 예정의 처리, 뒤에 실시해야하는 작업 등은 여기에 작성한다.

Todo:
   TODO리스트를 기재
    * conf.py의``sphinx.ext.todo`` 를 설정하지 않으면 사용할 수 없다.
    * conf.py의``todo_include_todos = True``로 하지 않으면 표시되지 않는다.

Shphinx로 변환후의 문서에 표시되도록 하기위해서는

Sphinx의 설정 파일 conf.py을 편집하고 아래와 같이 확장 기능 [sphinx.ext.todo]를 설정해 둘 필요가 있다.

extensions = [ 'sphinx.ext.todo' ]

todo_include_todos = True

---

참고자료

qiita.com/11ohina017/items/118b3b42b612e527dc1d