[python] Poetry를 사용하여 파이썬 패키지의 문서화와 예제 코드를 연동하여 사용자들에게 보다 쉽게 이해할 수 있는 도구를 제공할 수 있습니다.

04 Dec 2023

python

파이썬 패키지를 개발하면서 사용자들이 패키지를 보다 쉽게 이해하고 사용할 수 있도록 문서화와 예제 코드를 함께 제공하는 것이 중요합니다. 이를 도와주기 위해 Poetry를 사용할 수 있습니다. Poetry는 패키지 관리, 의존성 관리, 프로젝트 빌드, 배포 등을 편리하게 해주는 도구입니다.

Poetry 설치하기

Poetry는 파이썬 패키지로 설치할 수 있습니다. 아래의 커맨드를 실행하여 Poetry를 설치하세요.

pip install poetry

문서화하기

Poetry를 사용하여 패키지를 문서화하려면 다음 단계를 따르면 됩니다.

pyproject.toml 파일을 열고 [tool.poetry] 섹션에 다음과 같은 설정을 추가합니다.
```
 [tool.poetry.documentation]
 build = "sphinx"
```
다음 커맨드를 실행하여 Sphinx를 설치합니다.
```
 pip install sphinx
```
패키지 루트 디렉토리에서 다음 커맨드를 실행하여 Sphinx를 초기화합니다.
```
 poetry run sphinx-quickstart
```

source 디렉토리에 있는 conf.py 파일을 열고 다음과 같이 수정합니다.

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

 ...

 import your_package

 ...

 master_doc = 'index'

source/index.rst 파일을 열고 문서화할 내용을 작성합니다. 예를 들어, your_package 모듈에 대한 설명을 추가하려면 다음과 같이 작성할 수 있습니다.
```
 .. automodule:: your_package
    :members:
```
문서를 빌드하려면 다음 커맨드를 실행합니다.
```
 poetry run sphinx-build source build
```
빌드된 문서는 build 디렉토리에 생성됩니다. 이제 사용자들은 문서를 열어 패키지를 이해하고 사용할 수 있습니다.

예제 코드 추가하기

예제 코드를 문서와 함께 제공하면 사용자들이 패키지의 기능을 더욱 쉽게 이해할 수 있습니다. Poetry를 사용하면 예제 코드를 문서와 자동으로 연동시킬 수 있습니다.

source 디렉토리에 examples 디렉토리를 생성합니다.

examples 디렉토리에 예제 코드 파일을 추가합니다. 예를 들어, example.py라는 파일을 추가하고 다음과 같이 작성할 수 있습니다.

 def multiply(a, b):
     """
     두 수를 곱하는 함수입니다.

     :param a: 곱셈의 첫 번째 수
     :param b: 곱셈의 두 번째 수
     :return: 두 수의 곱
     """
     return a * b

 result = multiply(3, 4)
 print(result)  # 예상 출력: 12

index.rst 파일에 예제 코드를 추가합니다.

 Examples
 --------

 .. literalinclude:: ../examples/example.py
    :language: python

문서를 다시 빌드하고 예제 코드를 확인합니다.
```
 poetry run sphinx-build source build
```

이제 패키지 문서와 예제 코드가 함께 제공되어 사용자들이 보다 쉽게 이해하고 활용할 수 있게 되었습니다. Poetry와 Sphinx를 사용하여 문서화와 예제 코드를 효율적으로 관리하고 개발자 경험을 향상시킬 수 있습니다.