Docstring과 Sphinx

Python : Docstring, Sphinx

파이썬 프로젝트는 독스트링과 스핑크스의 강력한 조합을 활용하여 효율적으로 코드를 문서화 할 수 있습니다.

독스트링

독스트링(Docstring)은 함수, 클래스, 모듈 등의 코드 설명을 직접 코드 내에 작성하는 문자열입니다. 마치 책의 목차나 설명처럼 코드의 기능, 사용법, 예시 등을 간결하게 설명해 줍니다. 파이썬에서는 일반적으로 세 개의 따옴표로 감싸서 표현합니다.

 

주석 스타일은 Google, Numpydoc, Javadoc 스타일이 있습니다. 우리는 가장 많이 사용하는 Google 스타일을 사용 하겠습니다

#예시
def add(a, b):
  """두 수를 더하는 함수

  Args:
    a: 첫 번째 숫자
    b: 두 번째 숫자

  Returns:
    두 수의 합
  """
  return a + b

 

구글스타일 주석 정보

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

 

스핑크스

스핑크스(Sphinx)는 파이썬 프로젝트를 위한 강력한 문서 생성 도구입니다. 독스트링을 기반으로 HTML, PDF 등 다양한 형식의 문서를 자동으로 생성할 수 있습니다.

 

1. 스핑크스 라이브러리 설치

# Sphinx 설치
pip install sphinx

# Sphinx 테마 설치
pip install sphinx-rtd-theme

 

2. 문서저장 폴더 생성

docs 폴더 생성. 프로젝트 루트 경로에서 실행 합니다. 

sphinx-quickstart docs

 

정상적으로 실행되었을때 화면 입니다. 

 

3. conf.py 수정

conf.py 파일은 프로젝트 폴더 >> docs >> source 밑에 있습니다. 

extensions, html_theme 부분을 수정하시고, 3줄 코드 추가 합니다

# 수정
extensions = ['sphinx.ext.autodoc']
html_theme = 'sphinx_rtd_theme'

# 추가
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

 

4. rst 파일 생성

rst(reStructuredText)파일은 각종 문서꾸밈을 위한 마크업 구문 또는 이를 파싱하는 라이브러리 입니다. 

sphinx-apidoc -f -o docs/source .

 

5. index.rst 수정

index.rst 파일 위치는 프로젝트 폴더 >> docs >> source

아래처럼 modules 밑으로 동일하게 추가 합니다. 

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

 

6. 문서생성

doc 폴더로 이동 make html 

 

docs >> build >> html 폴더에 생성 됩니다. 끝!!

 

독스트링과 스핑크스는 파이썬 개발자에게 없어서는 안 될 강력한 도구입니다. 코드를 작성하는 것뿐만 아니라, 코드를 잘 설명하고 관리하는 것은 개발자의 중요한 역할이기 때문입니다. 독스트링과 스핑크스를 활용하여 더욱 효율적이고 체계적인 개발을 경험해 보시기 바랍니다.