Colin's Blog
[python] Poetry를 사용하여 파이썬 패키지의 버전과 변경 내역을 문서화하고 문제 해결을 위한 가이드를 제공할 수 있습니다.

파이썬 패키지를 개발하다보면 버전 관리와 변경 내역 문서화, 그리고 사용자들에게 문제 해결을 위한 가이드를 제공해야 하는 상황이 발생합니다. 이를 위해 Poetry라는 도구를 사용하여 효과적으로 문서화를 할 수 있습니다. 이번 블로그 포스트에서는 Poetry를 이용하여 파이썬 패키지의 버전과 변경 내역을 문서화하고, 사용자들에게 문제 해결을 위한 가이드를 제공하는 방법에 대해 알아보겠습니다.

Poetry란?

Poetry는 파이썬 프로젝트 관리를 위한 도구입니다. pyproject.toml 파일에 정의된 패키지 종속성을 관리하고, 가상 환경을 생성하여 의존성을 격리하는 기능을 제공합니다. Poetry를 사용하면 패키지의 버전을 쉽게 관리하고, 그에 따른 변경 내역과 가이드를 자동으로 생성할 수 있습니다.

버전 관리와 변경 내역 문서화

  1. Poetry를 설치합니다. Poetry 설치 가이드를 참고하세요.

  2. 프로젝트 디렉토리에서 다음 명령을 실행하여 pyproject.toml 파일을 생성합니다.

poetry init

  1. pyproject.toml 파일에 패키지 정보를 입력합니다. version 필드를 통해 패키지의 버전을 관리할 수 있습니다.

  2. 변경 내역을 기록할 CHANGELOG.md 파일을 생성합니다. 이 파일에는 각 버전별 변경 내용을 기록합니다.

  3. 프로젝트 루트 디렉토리에 poetry version 명령을 실행하여 버전을 업데이트하고, CHANGELOG.md 파일에 변경 내용을 추가합니다.

poetry version patch  # 패치 버전으로 업데이트
  1. 변경 내역을 기록할 때는 다음과 같은 형식을 따르는 것이 좋습니다.
## [X.Y.Z] - YYYY-MM-DD

### Added
- 새로운 기능 추가

### Changed
- 기존 기능 변경

### Deprecated
- 사용이 권장되지 않는 기능 목록

### Removed
- 제거된 기능 목록

### Fixed
- 버그 수정 사항
  1. 변경 내역을 추가한 후, 변경 내역 파일의 맨 위에 다음과 같은 내용을 추가합니다.
# Changelog

모든 중요한 변경 내용을 이 파일에 기록하세요.
  1. Git 저장소에 변경 내역을 커밋하고, 태그를 생성합니다.
git add CHANGELOG.md pyproject.toml
git commit -m "Update changelog and version"
git tag X.Y.Z
git push --tags

이제 버전 및 변경 내역이 문서화되었습니다.

문제 해결을 위한 가이드 제공

패키지를 사용하는 사용자들이 문제를 해결할 수 있도록 가이드를 제공하는 것은 매우 중요합니다. Poetry를 사용하여 다음과 같은 가이드를 제공할 수 있습니다.

  1. 프로젝트 루트 디렉토리에 docs 디렉토리를 생성합니다.

  2. docs 디렉토리에 index.md 파일을 생성하고, 패키지에 대한 개요와 설치 방법 등을 작성합니다.

  3. 다른 문서를 작성하기 위해 docs 디렉토리에 필요한 파일들을 추가로 생성합니다.

  4. pyproject.toml 파일을 열고, tool.poetry 섹션 아래에 다음과 같은 설정을 추가합니다.

[tool.poetry.scripts]
docs = "mkdocs serve"
  1. 프로젝트 루트 디렉토리에서 다음 명령을 실행하여 MkDocs를 설치합니다.
poetry add mkdocs mkdocs-material
  1. docs 디렉토리에서 다음 명령을 실행하여 MkDocs 프로젝트를 초기화합니다.
poetry run mkdocs new .

  1. mkdocs.yml 파일을 열고, 사이트의 설정을 수정합니다. 예를 들어, site_name을 패키지 이름으로 변경할 수 있습니다.

  2. 가이드 문서를 작성합니다. 필요한 페이지 수에 따라서 추가적인 .md 파일을 생성하고, MkDocs의 문서화 가이드를 참고하여 내용을 작성합니다.

  3. 가이드가 완성되면, 프로젝트 루트 디렉토리에서 다음 명령을 실행하여 가이드를 확인합니다.

poetry run mkdocs serve

위 명령을 실행하면 http://localhost:8000에서 가이드를 확인할 수 있습니다.

이제 Poetry를 사용하여 패키지의 버전과 변경 내역을 문서화하고, 사용자들에게 문제 해결을 위한 가이드를 제공할 수 있는 환경을 구축했습니다. 사용자들은 변경 내역을 확인하고, 가이드를 따라 문제를 해결할 수 있으며, 개발자는 패키지를 효과적으로 관리할 수 있습니다.

© 2018 Colin. All rights reserved.