用途:为准备发布到 PyPI 的 Python 包生成专业、合规的 README,支持 Markdown 与 reStructuredText 两种格式,并确保在 PyPI、GitHub、GitLab、BitBucket 上正确渲染。
主要能力:支持纯文本、reStructuredText(text/x-rst)和 Markdown(GFM 或 CommonMark)三种格式;提供格式选择建议;指导 README 必备章节(项目标识、安装、快速开始、功能、用法示例、文档链接、贡献、许可证等);给出 Markdown 与 RST 的语法示例(代码高亮、徽章、表格、提示框、链接、标题层级);说明 pyproject.toml 中 readme 与 content-type 的配置方式;提供构建、校验与发布流程。
必要用法:构建用 uv build;校验用 uv run --with twine twine check dist/;发布用 uv run --with twine twine upload dist/,可先上传 TestPyPI。Sphinx 项目可用 sphinx-readme 生成兼容 RST,安装命令为 uv add --group docs sphinx-readme。本地预览 Markdown 可用 uvx grip README.md,校验 RST 可用 uv run --with docutils rst2html.py README.rst /dev/null。
限制:PyPI 的 RST 渲染不允许 Sphinx 扩展,:py:func:、:ref:、:doc: 等角色及 automodule 等指令不可用,仅支持标准 docutils 指令;Sphinx 高级特性可能无法转换,发布前需人工检查生成结果。GitHub 与 PyPI 渲染存在差异,建议先在 TestPyPI 验证。
适用场景:新建 Python 包 README、Markdown 与 RST 互转、发布前校验标记、配置 pyproject.toml 元数据、从 Sphinx 文档生成 README.rst、排查 PyPI 渲染问题。具体模板与更多细节见资料中的参考文件,未提供的部分暂未说明。