Sphinx 5.1 特性深度解析：include_patterns、option_emphasise_placeholders 与 Docutils 0.19 支持

• 文档
• 开发工具

Sphinx 5.1（含补丁版本 5.1.0 与 5.1.1）于 2022 年 7 月发布，是 5.x 系列中承上启下的一个重要版本。本指南以仓库中的官方变更日志 doc/changes/5.1.rst 为骨架，系统讲解该版本引入的include_patterns配置、option_emphasise_placeholders选项、HTML/LaTeX 主题增强、Docutils 0.19 兼容性等核心变更，并结合sphinx/config.py、sphinx/project.py、sphinx/domains/std/__init__.py等源码与官方文档 doc/usage/configuration.rst、doc/latex.rst 进行源码级佐证。读完本文，你将掌握 5.1 版本的全部新特性、已知问题修复清单及其底层实现原理，能够据此评估升级路径并配置新选项。

版本概览

5.1.1 作为紧随 5.1.0 两日后发布的补丁版本，修复了 5.1.0 引入的回归问题，建议所有 5.1.0 用户在升级时直接使用 5.1.1。

新特性详解

1. 支持 Docutils 0.19（#10656）

5.1.0 起 Sphinx 官方支持 Docutils 0.19（2022-07-05 发布）。这意味着构建环境可以将docutils依赖升级到 0.19 而不会破坏 Sphinx 构建流程。

需要特别注意的是：5.1.0 的 HTML 主题在 Docutils 0.18 早期版本（非 0.18.1）下存在构建失败问题（详见下文"Bug 修复"章节的 #10596），原因是 Docutils 0.18 缺少Node.findall()方法。因此若停留在 Docutils 0.18 系列，应至少使用 0.18.1。

2. 新增include_patterns配置项（#10518）

include_patterns是exclude_patterns的对偶配置，用于正向指定需要纳入构建的源文件。

# conf.py include_patterns = ['**'] # 默认值：递归包含源目录下所有文件 include_patterns = ['library/xml'] # 仅包含 library/xml 目录 include_patterns = ['**/doc'] # 包含所有 doc 目录（文档与源码共存时很有用）

优先级规则：exclude_patterns的优先级高于include_patterns（见 doc/usage/configuration.rst）。也就是说，被exclude_patterns排除的文件即使匹配include_patterns也不会被纳入。

源码级原理：

• 配置注册于 sphinx/config.py：'include_patterns': _Opt(['**'], 'env', frozenset((str,)))，默认值为['**']，类型为字符串序列，属于环境级（'env'）配置。
• 文件发现流程：BuildEnvironment.find_files()在 sphinx/environment/init.py 中将exclude_patterns + templates_path + builder.get_asset_paths()作为排除路径，将include_patterns作为包含模式，一并传给Project.discover()。
• Project.discover()（sphinx/project.py）调用get_matching_files(srcdir, include_paths, [*exclude_paths, *EXCLUDE_PATHS])完成 glob 匹配，其中EXCLUDE_PATHS是 Sphinx 内置的默认排除项（如.git等）。匹配规则与exclude_patterns一致：模式针对相对于源目录的路径进行匹配，所有平台统一使用斜杠作为目录分隔符。

这一配置尤其适合"文档与源码混放"的仓库，可以精确圈定文档范围，避免把无关的.rst/.md文件卷入构建。

3. 新增option_emphasise_placeholders配置项（#10366）

该选项用于在option指令（std 域的命令行选项描述）中强调占位符。

# conf.py option_emphasise_placeholders = True

.. option:: -foption={TYPE} 如上配置下，``TYPE`` 会被强调渲染；要显示字面量花括号，需用反斜杠转义（``\{``）。

官方文档（doc/usage/configuration.rst）给出的示例：option_emphasise_placeholders=True且.. option:: -foption={TYPE}时，TYPE会被强调显示。该选项类型为bool，默认False，在 sphinx/config.py 注册为'option_emphasise_placeholders': _Opt(False, 'env', frozenset((bool,)))。

源码级原理：该选项在Cmdoption.handle_signature()（sphinx/domains/std/init.py）中生效：

• 选项签名按,分隔成多个潜在选项，逐个用option_desc_re正则校验；
• 当option_emphasise_placeholders开启时，多个选项之间使用desc_sig_punctuation(',')与desc_sig_space分隔（而非默认的desc_addname(', ')）；
• 参数部分会被samp_role.parse()解析：[/]/=等作为标点节点，其余文本作为强调节点输出，{TYPE}中的TYPE因此被强调渲染；
• 关闭时，参数整体作为desc_addname(args, args)输出（保持旧行为）。

4. HTML 主题：stylesheet支持多个 CSS 文件（#10444）

5.1 允许通过theme.conf的stylesheet设置指定多个 CSS 文件，也允许将html_style设为字符串可迭代对象：

# conf.py html_style = ['custom1.css', 'custom2.css']

此前stylesheet只能填单个文件，现在可以按顺序加载多个样式表，为复杂主题定制提供了便利。

5. HTML 主题：脚注包裹<aside>元素（#10599）

使用 Docutils 0.18 或更高版本时，连续的脚注会被包裹进<aside>元素，便于独立样式化。该行为与 Docutils 0.19 引入的行为保持一致，相当于在 5.1 中提前对齐了 Docutils 0.19 的输出结构。

6. LaTeX：CSS 风格命名的'sphinxsetup'键扩展（#10648）

5.1 为 LaTeX 输出引入了与 CSS 命名风格类似的'sphinxsetup'键，用于对code-block、topic、attention、caution、danger、error、warning这 7 类指令的盒子分别配置：

• 四条独立的border-width（border-width）
• 四个独立的padding（padding）
• 四个corner-radius（圆角半径）
• 阴影（shadow，可设为 inset 内阴影）
• 边框色、背景色、阴影色（border color、background color、shadow color）

示例配置（doc/latex.rst）：

latex_elements = { 'sphinxsetup': ( 'pre_border-width=2pt, ' # code-block 边框宽度 'pre_border-radius=3pt, ' # code-block 圆角 'div.warning_border-width=3pt, ' # warning 指令边框 ... ), }

这些键通过latex_elements['sphinxsetup']写入生成的.tex文件，也可在文档前导中使用\sphinxsetup{key1=value1, key2=value2, ...}LaTeX 宏直接设置（详见 doc/latex.rst 与 doc/latex.rst）。键的详细列表覆盖边框、内边距、圆角、阴影及颜色（含additionalcss等）。

7. LaTeX：LatinRules.xdy 中非标准编码的说明（#10655）

LatinRules.xdy（见 sphinx/texinputs/LatinRules.xdy）中使用的非标准编码在 5.1 中补充了说明文档，方便维护者理解 xindy 索引规则的编码约定。

8. std 域：警告信息使用变量 repr（#10439）

当 std 域显示警告时，部分变量改用repr形式输出，使空白字符等问题更容易被识别（例如不可见的前导/尾随空格会在引号中显现）。

9. quickstart：精简生成的conf.py（#10571）

sphinx-quickstart生成的conf.py模板内容被精简，去除了冗余注释，减少初始项目的噪音，让用户按需自行添加配置。

Bug 修复清单

HTML 主题

• #10594：使用 Docutils 0.18+ 时，字段名（field term）后的冒号出现重复。
• #10596：Docutils 版本恰为 0.18（而非 0.18.1）时，因缺少Node.findall()导致构建失败。
• #10520：修复agogo.css_t中 sidebar 类名的使用。
• #6679：修复 agogo 主题中隐藏 toctree 被错误包含的问题。
• #10566：修复enable_search_shortcuts设置不生效的问题。

HTML 搜索

• HTML 标签被当作对象名称的一部分显示——已修复。
• 搜索摘要（snippets）不应被折叠——已修复。
• 获取搜索摘要时发出次要错误——已修复。
• 搜索结果中显示了头部链接标记——已修复。
• #10548：修复搜索摘要的若干次要问题。

Python 域（py domain）

• #10550：修复反解析各种运算符（+、-、~、**）时出现的多余空白（refs: #10551）。
• #9577 / #10088：修复同时使用:any:与 autodoc 时重复 Python 引用产生的警告。

LaTeX

• #10506：图注（figure caption）中高亮行内代码角色导致构建错误（refs: #10251）。
• #8686：code-block 在页面末尾时文本可能溢出并在下一页留下残留物——已修复。
• #10633：用户在 topic 或 admonition 盒子中注入的\color命令可能因上游framed.sty缺陷导致 PDF 颜色泄漏。
• #10638：高亮代码中的彩色盒子（如使用 Pygments 样式'manni'的高亮 diff）错误继承了 code-block 边框厚度。
• #10647：desc_signature节点即使有多个节点 ID 也只生成一个\label——已修复。

其他

• #10634：使-P（pdb 调试）选项在事件触发的异常下工作得更好。
• #10460：日志中节点源码位置始终以绝对路径显示。
• #10579：i18n 在翻译 raw 指令时抛出UnboundLocalError——已修复。

5.1.1 补丁版本修复

5.1.1（2022-07-26 发布）仅包含两个修复：

• #10701：修复新的基于deque的sphinx.ext.napoleon迭代器实现中的ValueError。
• #10702：恢复与第三方 builder 的兼容性。

这两项修复直接对应 5.1.0 引入的回归：#10467 中 napoleon 迭代器被标记弃用并改用deque实现（见下文"弃用项"），以及 5.1.0 对内部接口的调整影响了第三方 builder。升级到 5.1.x 时应使用 5.1.1。

弃用项

5.1.0 引入两项弃用：

1. sphinx.util.stemmer（#10467）：推荐改用snowballstemmer。这意味着基于sphinx.util.stemmer的第三方代码应迁移，搜索相关的词干提取逻辑转向snowballstemmer库。
2. sphinx.ext.napoleon.iterators（#9856）：napoleon 扩展的迭代器模块被弃用，5.1 内部改用deque实现（该实现正是 5.1.1 中 #10701 修复的对象）。

弃用项会保留一段兼容期，但建议在新代码中立即使用替代方案。

升级与验证建议

1. 升级 Docutils：确认 Docutils 版本不低于 0.18.1，推荐直接使用 0.19 以享受官方支持。
2. 使用 5.1.1 而非 5.1.0：5.1.1 修复了两个回归问题，直接安装Sphinx>=5.1.1,<5.2即可。
3. 检查弃用警告：构建时留意sphinx.util.stemmer与sphinx.ext.napoleon.iterators的弃用警告，及时迁移依赖。
4. 验证新增配置：若启用include_patterns或option_emphasise_placeholders，通过sphinx-build -b html实际构建并检查输出文档树与选项指令渲染效果。
5. 第三方 builder 兼容性：若项目使用自定义或第三方 builder，升级到 5.1.0 后务必测试构建，确认不受 #10702 涉及的变化影响（5.1.1 已恢复兼容）。

参考资源

• 官方变更日志：doc/changes/5.1.rst
• include_patterns配置说明：doc/usage/configuration.rst
• option_emphasise_placeholders配置说明：doc/usage/configuration.rst
• 配置注册与默认值：sphinx/config.py
• 文件发现与 glob 匹配：sphinx/environment/init.py、sphinx/project.py
• option指令占位符强调实现：sphinx/domains/std/init.py
• LaTeX'sphinxsetup'完整文档：doc/latex.rst

• 文档
• 开发工具