doc8 文档发布前检查

解决什么问题

reStructuredText 的语法宽容度很高：一个缩进错位、一处超长行或一行缺失的空行，编辑器里看起来一切正常，到了 Sphinx 构建阶段才暴露成 WARNING: Inline literal start-string without end-string 之类的错误，或者发布说明在网页上被渲染得支离破碎。等到 CI 里跑 sphinx-build 才发现问题，修复成本要高得多——你需要先定位是哪个源文件、哪一行引入的，再回到几十条变更记录里排查。

这个技能的思路是把检查点前移：在文档和发布说明推送到 Sphinx 之前，先用 doc8 对它们做一次快速、确定性的静态扫描，把结构性错误和行风格问题挡在构建之外。

技能如何工作

核心依赖是 Python 环境里的 doc8 CLI。它面向的输入是仓库中的 reStructuredText 文档，也可以覆盖纯文本写成的文档源，因此同一个检查流程既适用于 docs/ 目录，也适用于 CHANGELOG、RELEASE_NOTES 之类的发布说明文件。

关键步骤：

• 选定检查范围：把 doc8 指向文档目录或发布说明所在的文件集合，确定本次要扫描的边界。
• 执行静态检查：doc8 逐文件解析 reStructuredText 结构，报告缩进不一致、行宽超限、行尾空白、缺少换行符等会污染渲染结果或干扰工具解析的问题。
• 处理报告项：按报错定位到具体文件和行号，修正后重新运行确认清零，再进入 Sphinx 发布流程。

需要强调的是，它检查的是格式与结构，不是文档内容本身的正确性。它不会验证你写的 API 名称是否存在，也不会判断措辞是否清晰。

适用边界与注意点

• 前提是环境就绪：仓库中需要有 Python 和可用的 doc8 CLI，且文档确实是 reStructuredText 或纯文本；面向 Markdown 的仓库不适用，应该换成对应的 Markdown 风格检查器。
• 它是门禁，不是替代品：doc8 通过不代表 Sphinx 构建一定成功。directive 用法错误、交叉引用断链这类问题仍会在构建阶段暴露，两者的检查维度不同。
• 规则配置要与项目约定对齐：默认规则不一定贴合你们团队的行长约定或文档目录结构，超出默认阈值的报错项需要先确认是改配置还是改文档。
• 一次改动要跑一次全量扫描：reStructuredText 的缩进和空行规则具有上下文相关性，局部修复可能影响相邻段落的解析结果，值得在发布前对目标目录整体重跑一遍。