文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载导读本文基于 Sphinx 官方发布检查清单 utils/release-checklist.rst 展开系统讲解 Sphinx 从准备发布、提升版本号、构建上传到进入下一开发版本bump to next development version的完整操作流程。读者将掌握 stable/major/beta 三类版本的差异、bump_version.py与bump_docker.sh两个脚本的底层工作原理以及如何在本地仓库复现这一套规范化的发布流程为自托管 Sphinx 或维护衍生文档项目提供可参考的发布模板。一、先厘清Sphinx 的三种版本类型发布流程的第一步是明确你要发布的版本属于哪一类。清单开篇给出了两个判定标准stable release稳定版minor 或 micro 版本号递增的发布。也就是说只要不是大版本号变化的发布都算稳定版例如8.4.x → 8.5.0、9.1.0 → 9.1.1。major release主版本major 版本号递增的发布例如8.x → 9.0.0。beta release预发布版清单中单独列出的第三类对应形如X.Y.0bN的版本号用于 major 版本正式发布前的测试期。关于版本号各段位的语义doc/internals/release-process.rst 给出了更细的约束major 段不兼容的行为变更或公开 API 更新时递增minor 段大多数保持向后兼容的常规发布时递增micro 段仅用于紧急的纯 bugfix 发布当 major 递增时minor 和 micro 必须归零当 minor 递增时micro 必须归零新的 major 版本在正式发布之前应当经历一个 beta 测试期。这正是清单中 stable/major 与 beta 两条分支流程存在差异的原因beta 版本无需推进到下一开发版本的新一轮开发周期之外的特殊处理其标记方式也以b后缀区分。二、发布前置检查Checks清单要求正式动手前先做两项体检检查 CI 状态打开仓库的 GitHub Actions 页面确认master分支上的所有测试均已通过。这一步确保发布基于一个完全健康的代码库。检查本地工作区干净运行git fetch; git status确认本地与远端同步、工作区没有未提交的改动。任何脏状态都可能导致发布构建混入预期之外的变更。这两步完成后才允许进入版本号提升阶段。从源码结构看这一环节的意义在于bump_version.py会直接改写 sphinx/init.py 中的版本常量并重写 CHANGES.rst 的标题行如果工作区存在未提交内容git 提交记录将难以回溯核对。三、提升版本号bump_version.py 的三种用法3.1 stable 与 major 发布稳定版和主版本使用同一套命令以目标版本X.Y.Z为例python utils/bump_version.py X.Y.Z git diff # 检查改动是否符合预期 git commit -am Bump to X.Y.Z final git tag vX.Y.Z -m Sphinx X.Y.Z流程要点bump_version.py只负责改写版本相关文件不负责提交因此紧接着需要人工git diff复核再提交并打上带注释的 tag。tag 命名为vX.Y.Z带v前缀tag 信息为Sphinx X.Y.Z。3.2 beta 发布beta 版本把micro位固定为0并在末尾追加bN序号python utils/bump_version.py X.Y.0bN git diff git commit -am Bump to X.Y.0 betaN git tag vX.Y.0b1 -m Sphinx X.Y.0bN注意清单原文中 tag 写法为vX.Y.0b1即首个 beta 的序号提交信息则写为Bump to X.Y.0 betaN。例如从9.0.x走向9.1.0的 beta 周期第一次执行时会写python utils/bump_version.py 9.1.0b1、git tag v9.1.0b1。3.3 脚本到底改了什么源码级剖析utils/bump_version.py 的核心逻辑非常值得研究它一次完成三件事1重写 sphinx/init.py 的版本常量bump_version()函数逐行扫描文件替换三行以Final结尾的赋值if line.startswith(__version__: Final ): lines[i] f__version__: Final {version}\n if line.startswith(version_info: Final ): lines[i] fversion_info: Final {version_info.release_tuple}\n if line.startswith(_in_development ): lines[i] f_in_development {in_develop}\n对照当前仓库的 sphinx/init.py 可以看到这三行的真实形态__version__: Final 9.1.1 version_info: Final (9, 1, 1, beta, 0) _in_development True其中version_info是一个五元组(major, minor, micro, releaselevel, serial)releaselevel取值只能是alpha、beta、rc、final对应脚本中VersionInfo.releaselevel属性的映射逻辑见bump_version.py第 31-42 行。而_in_development True时__init__.py还会尝试执行git rev-parse --short HEAD把当前提交的短哈希拼接到__display_version__后面形如9.1.1/a1b2c3d便于开发版本在命令行中直接显示来源 commit。2改写 CHANGES.rst 的发布标题Changes类读取 CHANGES.rst 的首行格式必须匹配Release X.Y.Z (in development)或Release X.Y.Z (released date)。当发布为 final 且当前处于开发中状态时finalise_release_date()会把in development替换成由time.strftime(%b %d, %Y)生成的真实发布日期如Dec 31, 2025并顺带过滤掉空白的变更章节filter_empty_sections。当版本号不同时add_release()则会从 utils/CHANGES_template.rst 读取模板在文件顶部插入一个新的Release X.Y.Z (in development)标题及 Dependencies / Incompatible changes / Deprecated / Features added / Bugs fixed / Testing 六个空章节。3版本号解析与校验脚本用parse_version()解析命令行传入的版本字符串支持两种合法形态纯数字X.Y.Z也允许简写X.Y此时 micro 视为 0解析为 final 版本预发布X.Y.ZaN、X.Y.ZbN、X.Y.ZrcN分别对应 alpha、beta、rc。任何不符合规则的输入都会直接抛出RuntimeError: Unknown version。另外main()中还有一个防御性检查如果目标版本与 CHANGES 首行版本一致且不是从开发版转为 final脚本会打印skip: version not changed并跳过改写避免重复发布同一版本号。四、构建并上传发布包版本号确认无误后进入构建与上传环节make clean python -m build . twine upload dist/Sphinx-*随后打开 PyPI 上Sphinx的项目页面检查发布结果是否有明显错误如描述渲染异常、文件缺失等。这三步的仓库依据分别对应make clean在 Makefile 中定义了完整的清理目标删除 Python 缓存、备份文件、doc/build/、build/sphinx/、测试产物tests/build以及根目录build/确保构建产物不会污染源码树python -m build .即 Makefile 中build目标执行的命令底层由 pyproject.toml 声明的构建后端flit_core3.12驱动产出dist/下的源码包与 wheel 包twine upload dist/Sphinx-*使用 twine 将产物上传至 PyPISphinx-*通配符同时覆盖 sdist 与 wheel 两类文件。4.1 stable 与 major 发布同步 Docker 镜像仅当发布为 stable 或 major 时还需要额外执行sh utils/bump_docker.sh X.Y.Zutils/bump_docker.sh对应源码 utils/bump_docker.py会进入同级的sphinx-docker-images仓库修改base/Dockerfile与latexpdf/Dockerfile两处内容更新LABEL org.opencontainers.image.versionX.Y.Z即 Open Container Initiative 标准的镜像版本标签更新SphinxX.Y.Z依赖声明让镜像内的 Sphinx 安装固定到刚发布的版本。随后脚本在 Docker 镜像仓库中依次执行git checkout master、提交Bump to X.Y.Z、打 tagX.Y.Z并推送到upstream从而保持 Docker 镜像与 PyPI 包版本完全同步。beta 发布跳过此步因为镜像只跟随正式版。五、提升到下一开发版本--in-develop发布包上传完成后仓库需要立即切换到下一个开发周期避免后续提交被误归入已发布版本。5.1 stable 与 major 发布之后python utils/bump_version.py --in-develop X.Y.Z1b0 # 例如 1.5.3b0--in-develop标志告诉脚本本次改写不是正式发布而是把__version__设为X.Y.Z1的 beta 0 形态_in_development保持为True同时为下一个版本在 CHANGES.rst 顶部创建(in development)章节。5.2 beta 发布之后python utils/bump_version.py --in-develop X.Y.0bN1 # 例如 1.6.0b2beta 之后只递增 beta 序号例如发布9.1.0b1后进入9.1.0b2的开发状态直到 beta 周期结束、发布 final 版本。这里有一个容易混淆的细节bump_version()内部对in_develop与版本形态的处理是——当in_developTrue或版本为 final 时__version__写入纯X.Y.Z形式的version否则写入带a/b/rc后缀的release形式。也就是说beta 正式发布不带--in-develop时__version__会呈现为9.1.0b1而开发版则保持纯数字加_in_development True的形态。六、提交版本变更并推送无论哪种发布类型最终都要落盘到远端git diff git commit -am Bump version git push origin master --tagsgit diff再次复核bump_version.py对sphinx/__init__.py与CHANGES.rst的全部改动git commit -am Bump version提交这一提交与第三节中发布时的Bump to X.Y.Z final提交是两步不同的提交前者是发布 tag后者是开发版本切换git push origin master --tags同时推送master分支和全部 tag包括vX.Y.Z与 Docker 仓库的X.Y.Z。七、发布收尾Final steps推送完成后清单要求完成两项社区运营工作更新 issue 追踪器在追踪器tracker中为新增版本/里程碑milestone建立分类便于后续 issue 按版本归档撰写发布公告将发布说明分别发送到sphinx-dev、sphinx-users邮件列表以及python-announce通知社区新版本特性、修复与升级注意点。公告内容通常可参考 CHANGES.rst 中该版本的变更章节Dependencies、Features added、Bugs fixed 等提炼要点。八、全流程速查与常见问题8.1 三种发布类型操作对照表环节stable / majorbeta版本示例9.1.1、10.0.09.1.0b1提升版本python utils/bump_version.py X.Y.Zpython utils/bump_version.py X.Y.0bN发布提交git commit -am Bump to X.Y.Z finalgit commit -am Bump to X.Y.0 betaN发布 taggit tag vX.Y.Z -m Sphinx X.Y.Zgit tag vX.Y.0b1 -m Sphinx X.Y.0bN构建上传make clean python -m build . twine upload dist/Sphinx-*同左Docker 同步sh utils/bump_docker.sh X.Y.Z跳过下一开发版python utils/bump_version.py --in-develop X.Y.Z1b0python utils/bump_version.py --in-develop X.Y.0bN18.2 常见问题Qbump_version.py提示Unknown version传入的版本号不符合X.Y、X.Y.Z或X.Y.ZaN/bN/rcN三种合法格式之一例如写成了v9.1.1或9.1之外的畸形串。--in-develop模式下同样受此规则约束。Q为什么 CHANGES 首行版本与目标一致时报skipmain()检测到changes.version_tuple version.version_tuple且不是开发版转 final时会以Skip异常跳过改写防止同版本重复发布。若确实需要重跑应先把 CHANGES 首行切回(in development)状态。Q开发版与正式版的__version__有何区别正式版在 sphinx/init.py 中_in_development False、__version__为纯版本号开发版_in_development True__display_version__会附带git rev-parse --short HEAD得到的提交短哈希方便区分不同开发快照。Q发布前必须满足哪些仓库前提清单明确要求master分支 CI 全绿对应发布前置检查且git fetch; git status确认工作区无未提交改动版本策略上还应遵守 doc/internals/release-process.rst 中对 major/minor/micro 递增规则的约定major 递增后 minor/micro 归零等。结语Sphinx 的发布流程是一套高度脚本化、可复现的工程实践bump_version.py承担版本号与 CHANGES 的原子改写python -m buildtwine负责交付物生成与上传bump_docker.py保持 Docker 镜像同步最后通过--in-develop无缝切换回开发周期。对于维护文档工具链或希望建立规范化版本发布流程的团队这份清单及其配套脚本utils/bump_version.py、utils/bump_docker.py、Makefile、pyproject.toml本身就是一份可直接借鉴的发布自动化模板。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐NetBox 版本发布全流程指南从 Release Checklist 到 PyPI 发布实战NetBox 版本发布全流程指南从 Release Checklist 到 PyPI 发布实战 本篇技术指南围绕 NetBox 官方开发文档中的发布清单Re后端网络数据建模TextBlob 版本发布流程全解析从版本号提升到 PyPI 自动发布TextBlob 版本发布流程全解析从版本号提升到 PyPI 自动发布 TextBlob 是一个提供统一 API 的 Python 文本处理库涵盖情感分析、NLP人工智能OmniRoute 发布清单Release Checklist实战指南从版本号提升到 npm OIDC 发布与回滚的完整流程OmniRoute 发布清单Release Checklist实战指南从版本号提升到 npm OIDC 发布与回滚的完整流程 导读 本文基于 OmniRo后端API网关LLM 网关人工智能大模型MCP 服务桌面应用上一篇Kong多集群管理跨数据中心流量调度下一篇Kubernetes 如何用 make test-integration 运行 test/integration 集成测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考