项目模板现代化升级

[SongshGeo]

概述

本次更新将项目模板迁移到现代化的工具链，提升开发体验和维护效率。

主要变更

1. 包管理器迁移

• 新增: 使用 uv 作为主要包管理器（保留 poetry 兼容）
• 更新所有命令支持 uv 和 poetry 自动切换
• Makefile 自动检测并选择合适的包管理器
• 更新 pyproject.toml 添加 [project] 标准配置

2. 依赖和工具更新

• 更新: Python 版本要求从 3.8.1-3.12 升级到 3.10-3.14
• 新增: interrogate 工具用于文档覆盖率检查（要求 80%）
• 修改: nbstripout 默认保留 notebook 输出（添加 --keep-output 参数）
• 新增: tox 支持，自动测试多 Python 版本（3.10-3.13）

3. 测试改进

• 新增: 为配置脚本添加完整测试套件（tests/test_configure_project.py）
• 新增: Makefile 快捷命令
  • make tox - 测试所有 Python 版本
  • make tox-e pyversion=<version> - 测试特定版本
  • make tox-list - 查看可用环境
• tox.ini 使用 deps = -e {toxinidir}[dev] 自动安装所有依赖

4. 文档系统升级

• 新增: MkDocs + Material 主题文档网站
• 新增: GitHub Actions 自动部署文档到 GitHub Pages
• 新增: 5个详细的文档章节
  • 快速开始指南
  • 工具链说明
  • 配置说明
  • 开发规范
  • 部署指南
• 新增: 文档首页和项目索引

5. Pre-commit 更新

• 移除: poetry-export hook
• 修改: nbstripout hook 添加 --keep-output 参数
• 新增: interrogate hook 检查文档覆盖率

6. CI/CD 更新

• 更新: release-please.yml 使用 uv 替代 poetry
• 新增: docs.yml 自动部署文档到 GitHub Pages
• 更新: 构建和发布流程使用 uv

7. 配置和文档

• 更新: README.md 添加快速开始和详细说明
• 更新: Makefile 所有命令支持 uv/poetry 自动切换
• 更新: 配置脚本添加完整文档字符串（达到 100% 覆盖率）

新增文件

• mkdocs.yml - MkDocs 配置
• docs/index.md - 文档首页
• docs/doc/*.md - 5 个详细文档章节
• tests/test_configure_project.py - 配置脚本测试
• .github/workflows/docs.yml - 文档部署工作流

改进文件

• pyproject.toml - 添加 [project] 配置，更新依赖
• tox.ini - 使用自动依赖安装，支持 Python 3.10-3.13
• makefile - 添加 tox 和文档相关命令
• README.md - 完善文档说明
• scripts/configure_project.py - 添加完整文档字符串
• .pre-commit-config.yaml - 更新 hooks 配置

使用示例

# 安装依赖（自动选择 uv 或 poetry）
make setup

# 运行测试
make test

# 测试所有 Python 版本
make tox

# 查看文档
make docs

# 部署文档（自动）
git push origin main  # 自动触发 GitHub Actions

向后兼容性

• 保留 poetry 配置，现有项目仍可使用 poetry
• 所有 Makefile 命令向后兼容
• 配置文件保持原有结构

测试状态

• ✅ 所有 Python 版本（3.10-3.13）测试通过
• ✅ 所有 lint 检查通过
• ✅ 文档覆盖率 100%
• ✅ tox 测试通过

文档

在线文档：https://songshgeo.github.io/project_template/

注意事项

• 首次部署需要在 GitHub 仓库设置中启用 GitHub Pages
• 建议安装 uv 以获得更好的性能
• 所有依赖已更新到最新稳定版本