构建与打包¶
本指南介绍了如何构建、测试和打包 Django Admin Dashboards 以供分发。
开发构建¶
本地开发安装¶
用于本地开发和测试：
这会创建一个可编辑的安装，源代码的更改会立即反映出来。
测试构建流程¶
在不上传到 PyPI 的情况下测试构建流程：
# 构建源代码分发和 wheel
python -m build
# 输出将在 dist/ 目录中：
# - django_admin_dashboards-0.1.1.tar.gz (源代码分发)
# - django_admin_dashboards-0.1.1-py3-none-any.whl (wheel)
包结构¶
核心文件¶
Django Admin Dashboards 主包结构如下：
django_admin_dashboards/
├── __init__.py # 包元数据和版本导出
├── admin.py # Django Admin 集成
├── apps.py # Django 应用配置
├── base.py # 基类：Dashboard、Component、Layout 等
├── models.py # 数据库模型（如有）
├── views.py # 自定义视图（如有）
├── urls.py # URL 配置
├── contrib/ # 贡献的组件和功能
│ └── auth/ # 认证应用相关
│ ├── __init__.py # 包初始化
│ └── dashboard.py # Auth 应用数据看板实现
├── templatetags/ # 模板标签
│ └── dashboard_tags.py # 数据看板渲染标签
├── static/django_admin_dashboards/ # 静态资源
│ ├── css/ # CSS 样式文件
│ │ ├── dashboard.css # 全局数据看板样式
│ │ ├── card.css # 卡片组件样式
│ │ ├── chart.css # 图表组件样式
│ │ ├── table.css # 表格组件样式
│ │ └── filter.css # 过滤器组件样式
│ └── js/ # JavaScript 文件
│ ├── dashboard.js # 全局数据看板 JavaScript
│ ├── card.js # 卡片组件 JavaScript
│ ├── chart.js # 图表组件 JavaScript
│ ├── table.js # 表格组件 JavaScript
│ └── filter.js # 过滤器组件 JavaScript
├── templates/admin/ # 数据看板模板
│ ├── dashboard.html # 主数据看板模板
│ ├── index.html # Admin 首页覆盖模板
│ ├── app_index.html # 应用页面覆盖模板
│ └── components/ # 组件模板
│ ├── card.html # 卡片组件模板
│ ├── chart.html # 图表组件模板
│ ├── table.html # 表格组件模板
│ └── filter.html # 过滤器组件模板
└── locale/ # 翻译文件
└── zh_Hans/ # 中文（简体）翻译
└── LC_MESSAGES/
├── django.po # 翻译源文件
└── django.mo # 编译后的翻译文件
包配置 (pyproject.toml)¶
该项目使用现代 Python 打包方式，使用 pyproject.toml：
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "django-admin-dashboards"
version = "0.1.1"
description = "可定制的 Django Admin 数据看板，包含卡片、图表、表格和过滤器"
# ... 其他配置
关键部分：
[构建-system]: 构建后端和要求[项目]: 包元数据、依赖项、分类器[项目.可选-dependencies]: 开发依赖项[tool.setuptools]: 包数据包含
包数据¶
静态文件和模板通过 package_data 配置包含：
[tool.setuptools.package-data]
"django_admin_dashboards" = [
"locale/*/LC_MESSAGES/*.mo", # 编译的翻译文件
"static/**/*", # 所有静态文件
"templates/**/*", # 所有模板文件
]
这确保所有必要的文件都包含在分发中。
测试包¶
本地包测试¶
- 构建包：
- 从本地构建安装：
# 创建测试用的虚拟环境
python -m venv test_env
source test_env/bin/activate # 在 Windows 上：test_env\Scripts\activate
# 安装构建的包
pip install dist/django_admin_dashboards-0.1.1-py3-none-any.whl
- 验证安装：
集成测试¶
使用演示项目测试已安装的包：
# 导航到演示项目
cd django_admin_dashboards_demo
# 安装本地包
pip install ../dist/django_admin_dashboards-0.1.1-py3-none-any.whl
# 运行数据库迁移
python manage.py migrate
# 收集静态文件
python manage.py collectstatic --noinput
# 运行开发服务器
python manage.py runserver
访问 http://localhost:8000/admin/ 以验证数据看板正常工作。
测试套件¶
运行完整的测试套件：
# 运行示例应用测试
pytest django_admin_dashboards_example -v
# 运行覆盖率测试
pytest django_admin_dashboards_example --cov=django_admin_dashboards --cov-report=html
构建分发版本¶
源代码分发 (sdist)¶
源代码分发包含所有源文件，并且与平台无关：
生成的 .tar.gz 文件包含：
- Python 源代码
- 静态文件和模板
- 翻译文件
- 文档（如果包含）
- 许可证和README
Wheel 分发 (bdist_wheel)¶
Wheel 分发是构建好的包，安装速度更快：
生成的 .whl 文件：
- 与平台无关（纯 Python）
- 安装更快
- 包含编译的字节码
通用 Wheels¶
由于该包是纯 Python（无 C 扩展），它会自动构建通用 wheels。
质量检查¶
构建前检查¶
在创建分发版本前运行这些检查：
# 1. 运行测试
pytest
# 2. 检查代码风格
flake8 django_admin_dashboards/
# 3. 格式化代码
black django_admin_dashboards/
# 4. 检查包元数据
python -m twine check dist/*
# 5. 验证静态文件是否包含
python -c "from django_admin_dashboards import __version__; print(f'Version: {__version__}')"
静态文件验证¶
确保所有静态文件都正确包含：
# 检查找到哪些静态文件
python -c "
import os
from django_admin_dashboards import __file__ as pkg_file
pkg_dir = os.path.dirname(pkg_file)
static_dir = os.path.join(pkg_dir, 'static', 'django_admin_dashboards')
if os.path.exists(static_dir):
for root, dirs, files in os.walk(static_dir):
for file in files:
print(os.path.join(root, file))
"
版本管理¶
更新版本¶
在两个地方更新版本：
-
pyproject.toml: -
DJANGO_ADMIN_DASHBOARDS/__init__.py:
版本格式¶
遵循语义化版本控制：
主版本号：不兼容的API变更次版本号：向后兼容的新功能修订号：向后兼容的bug修复
示例：0.1.0 → 0.2.0（包含新功能的次版本发布）
发布到 PyPI¶
先决条件¶
- PyPI 账户：在 PyPI.org 注册
- API 令牌：创建具有上传权限的令牌
- twine：使用
pip install twine安装
测试 PyPI¶
首先，上传到测试 PyPI：
# 上传到测试 PyPI
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
# 从测试 PyPI 安装以验证
pip install --index-url https://test.pypi.org/simple/ django-admin-dashboards
生产 PyPI¶
测试后，上传到生产 PyPI：
# 上传到 PyPI
python -m twine upload dist/*
# 为自动化设置环境变量
# export TWINE_USERNAME=__token__
# export TWINE_PASSWORD=pypi-your-token-here
自动化发布¶
对于 CI/CD 流水线，使用基于令牌的身份验证：
# GitHub Actions 工作流示例
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ secrets.PYPI_API_TOKEN }}
文档构建¶
本地文档¶
在本地构建和提供文档：
# 安装文档依赖项
pip install mkdocs mkdocs-material mkdocstrings-python
# 提供文档服务
mkdocs serve
# 构建静态站点
mkdocs build --site-dir site/
Read the Docs¶
文档已配置为 Read the Docs：
- 将 GitHub 仓库连接到 Read the Docs
- 启用推送时的自动构建
- 在
.readthedocs.yaml中配置 Python 版本和依赖项
.readthedocs.yaml 示例：
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.11"
python:
install:
- method: pip
path: .
extra_requirements:
- dev
sphinx:
configuration: docs/conf.py
fail_on_warning: true
常见构建问题¶
缺少静态文件¶
问题：静态文件 (CSS, JS) 未包含在分发中。
解决方案：验证 pyproject.toml 包含：
模板未找到¶
问题：安装后找不到模板。
解决方案：确保模板在 templates/ 目录中并包含在 package_data 中。
翻译文件缺失¶
问题：.mo 文件未编译或缺失。
解决方案：
# 编译翻译文件
cd django_admin_dashboards
django-admin compilemessages
# 验证 .mo 文件是否存在
ls locale/*/LC_MESSAGES/*.mo
版本冲突¶
问题：pyproject.toml 和 __init__.py 中的版本不匹配。
解决方案：保持两个文件中的版本同步。
发布检查清单¶
在每次发布前，完成此检查清单：
代码质量¶
- [ ] 所有测试通过 (
pytest) - [ ] 代码使用 Black 格式化 (
black .) - [ ] 代码检查通过 (
flake8) - [ ] 没有损坏的导入或语法错误
文档¶
- [ ] README.md 已更新
- [ ] 文档构建成功 (
mkdocs build) - [ ] 更新了变更日志（如果维护）
- [ ] 示例正常工作
打包¶
- [ ] 在
pyproject.toml和__init__.py中更新版本 - [ ] 包构建成功 (
python -m build) - [ ] 静态文件已包含 (
pip show -f) - [ ] 测试安装有效 (
pip install dist/*.whl)
测试¶
- [ ] 演示项目与新版本兼容
- [ ] 所有功能已手动测试
- [ ] 浏览器兼容性已检查
- [ ] 移动设备响应性已验证
分发¶
- [ ] 测试 PyPI 上传成功
- [ ] 生产 PyPI 上传准备就绪
- [ ] 为发布创建 Git 标签
- [ ] 发布说明已准备
持续集成¶
推荐 CI 配置：
GitHub Actions 示例¶
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install -e ".[dev]"
- run: pytest
- run: flake8 django_admin_dashboards/
- run: black --check django_admin_dashboards/
build:
runs-on: ubuntu-latest
needs: test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install build twine
- run: python -m build
- run: python -m twine check dist/*