企业官网建设流程全解析

• 文档
• 开发工具

Sphinx 3.0 系列（2020 年 4–5 月发布，含 3.0.0–3.0.4）是一次大型主版本更新，重写了 C 语言域、改造了 Python 域的内部数据结构，并为 autodoc、autosummary、HTML 主题与 LaTeX 输出引入了大量新配置项。本文基于 doc/changes/3.0.rst 变更记录，逐项解读 3.0 的破坏性变更、新增特性、弃用 API 与 bug 修复，并结合当前仓库源码验证关键配置的实现位置，为从 Sphinx 1.8/2.x 升级到 3.x 的开发者提供可落地的迁移参考。

一、版本概览与升级背景

Sphinx 3.0.0 于 2020 年 4 月 6 日发布，此后 3.0.1、3.0.2、3.0.3、3.0.4 为修复性补丁版本。作为主版本号提升，3.0 系列延续了 Sphinx 的一贯策略：移除 1.8.x 中已弃用的特性与 API，并对多个核心域（domain）的内部结构做出不兼容调整。升级到 3.0 意味着需要同时关注行为变化与代码迁移两个层面。

3.0 版本同时存在两条开发线：

• 3.0.0b1：承载了绝大多数新特性与破坏性变更；
• 3.0.0 final：在 beta 基础上补充少量 API 调整（如unwrap_all()更名）与修复。

依赖方面，3.0.0b1 引入了两项变化：LaTeX 构建在日文文档中不再依赖extractbb生成.xbb文件（自 TeXLive2015 起dvipdfmx已不再需要它们，见 issue #6189）；同时 babel 2.0 及以上版本可用且不再被固定版本号锁定（Unpinned）。

二、破坏性变更（Incompatible Changes）逐项解读

3.0 的破坏性变更集中在域（domain）内部结构、autodoc 行为与配置默认值上，按主题可归纳为六类。

2.1 autodoc / autosummary 行为变化

• autosummary stub 文件默认自动覆盖（#247）：autosummary_generate生成的.rst存根文件在 3.0 中默认被自动重写，这是对旧版本行为的显式反转。该配置项在 sphinx/ext/autosummary/init.py 中注册，默认值为True：

  app.add_config_value( 'autosummary_generate', True, 'env', types=frozenset({bool, list}) ) app.add_config_value( 'autosummary_generate_overwrite', True, '', types=frozenset({bool}) )

  生成流程由builder-inited事件触发（app.connect('builder-inited', process_generate_options)），在 sphinx/ext/autosummary/init.py 中把overwrite=app.config.autosummary_generate_overwrite传给generate_autosummary_docs()。若希望保留手工维护的 stub 文件，需在conf.py中显式设置：

  autosummary_generate_overwrite = False

• object类的成员默认不再被文档化（#5923）：当同时使用:inherited-members:与:special-members:时，object基类的成员（如__init__之外的魔术方法）不再被列出。同时:inherited-members:选项现在可接收一个祖先类名，用于限定"不要文档化该祖先类及其上层"的继承成员。

• autodoc_typehints新增"description"模式（#7079）：类型注解可以从函数签名中剥离，改以"对象描述"（object description）形式呈现。当前仓库中该配置的合法取值集合为（见 sphinx/ext/autodoc/_shared.py）：

  autodoc_typehints: Literal['signature', 'description', 'none', 'both'] autodoc_typehints_description_target: Literal['all', 'documented params', 'undocumented params'] autodoc_typehints_format: Literal['fully-qualified', 'short'] = 'short'

  3.0 中autodoc_typehints = 'description'还会影响autodoc_typehints_description_target（限定描述目标为"所有参数/已文档化参数/未文档化参数"）。需要注意的是，该模式下类与方法的类型注解必须配合正确配置才能被抑制（见 3.0.1 修复项 #7435）。

• info-field-list 中的meta字段成为保留字段（#6830）：Python 域中:meta private:之类的元字段不再显示在输出文档中，同时 autodoc 会把包含:meta private:的成员视为私有成员。实现上，Python 域通过新事件object-description-transform注册了过滤器（见 sphinx/domains/python/init.py）：

  app.connect('object-description-transform', filter_meta_fields)

2.2 Python 域（py domain）的内部结构调整

• desc_parameterlist 的 doctree 结构改变（#6417）：函数/方法的参数名、注解与默认值现在分别包裹在独立的 inline 节点中，这使得为参数定制样式成为可能（对应新特性"Allow to make a style for arguments"）。
• 内部索引数据结构升级（#6903）：Python、reST 与标准域的对象/模块索引中加入了node_id，交叉引用从此保存(docname, node_id)二元组，为更精确的链接定位提供基础。
• 移除特殊交叉引用辅助机制（#7246）：异常、函数与方法的特殊交叉引用 helper 被移除；同时say_hello_这类"尾随下划线"链接到.. py:function:: say_hello()的非预期行为被清除（#6903）。注意：numref_（#7229）、parseInt_（#7210）、say_hello_（#7276，C++ 域）等旧式链接写法在 3.0 中全部失效，需要改用标准的:ref:、:py:func:、:cpp:func:等角色。
• lambda 函数签名支持：py domain 现在可以解析 lambda 表达式形式的函数签名。
• 对已存在同名对象发出警告（#7238/#7239）：描述一个与既有条目同名的 Python 对象时，构建会给出重复定义警告，帮助及早发现命名冲突。

2.3 C 语言域全面重写

3.0 最引人注目的变化是C domain 的完整重写。原有指令与角色变得更严格（更严格的解析意味着会产生更多新警告），同时带来了大量新能力：

• 交叉引用尊重当前作用域（cross-referencing respecting the current scope）；
• 支持文档化匿名实体（anonymous entities）；
• 为每种实体类型提供更具体的指令与角色，例如枚举器（enumerator）的作用域处理；
• 新增c:expr角色，用于在正文中渲染表达式与类型。

C++ 域也同步受益：修复了涉及函数重载与多声明指令的交叉引用查找（#5078），并支持备用运算符拼写（alternate operator spellings，如and/or，#7367）。3.0.3 进一步为 C 语言域加入了数组声明符的解析能力（static、qualifiers 与 VLA 规范），3.0.2 则为 C 语言域新增了属性解析支持。

2.4 配置默认值与解析器变化

• strip_signature_backslash新增配置（#6462）：在 3.0 之前，域指令中的双反斜杠\\会被默认替换为单反斜杠\；3.0 起这一行为默认关闭。如需恢复旧行为，在conf.py中设置：

  strip_signature_backslash = True

  该配置项当前在 sphinx/ext/autodoc/_shared.py 中声明、默认值为False，并被 napoleon、autodoc 与 directives 模块共同读取。

• productionlist指令的作用域语义生效（#3077）：按文档规范实现了productionlist的作用域（scope）机制。旧用法中某些token角色必须补上此前被忽略的作用域前缀；同时新增反斜杠续行支持（#1027）。productionlist节点定义于 sphinx/addnodes.py，在标准域中注册（见 sphinx/domains/std/init.py）。

• C 域新增属性配置项（3.0.2，#见变更记录）：:confval:c_id_attributes与 `:confval:`c_paren_attributes用于声明用户自定义属性，使 C 解析器能够识别非标准属性语法。两者在 sphinx/domains/c/init.py 注册，默认均为空列表，类型为list/tuple，并在 sphinx/domains/c/_parser.py 中被解析器读取。

• ConfigError可从 conf.py 抛出（#7108）：配置阶段允许通过抛出ConfigError向用户展示来自conf.py的错误信息，该类定义于 sphinx/errors.py。

2.5 事件系统与节点结构变化

• sphinx.events.EventManager.listeners结构改变：事件监听器的内部存储结构调整，直接依赖该属性的第三方扩展需要适配。
• sphinx_cpp_tagname属性更名为sphinx_line_type：desc_signature_line节点上的该属性在 3.0 中改名。
• 事件处理器支持优先级（priority）：Sphinx.connect()现在允许为事件处理器指定优先级，扩展可以更精确地控制多个处理器之间的执行顺序。
• ObjectDescription.transform_content()新增（3.0.0 final）：域对象描述节点在输出前可通过该钩子转换内容，当前实现见 sphinx/directives/init.py 与标准域中的对应实现（sphinx/domains/std/init.py）。

2.6 其他行为变化

• 3.0.1 起，标准域term角色变为大小写敏感（#7418），同时 glossary 重复词条警告改为大小写不敏感；term角色不再能大小写不敏感地匹配。
• sphinx.util.inspect.unwrap()在 3.0 final 中更名为unwrap_all()（#7222），当前实现位于 sphinx/util/inspect.py，它比inspect.unwrap更进一步：会连续解包 partial 函数、__wrapped__链、类方法与静态方法，直至拿到原始对象。

三、新增特性全景（Features Added）

除上述破坏性变更外，3.0 引入了大量面向使用者的新能力，以下按扩展模块归类。

3.1 autodoc 增强

• 支持Annotated类型（PEP 593）（#7165）：autodoc 现在能正确渲染typing.Annotated携带的元数据。
• 支持singledispatch泛型函数与方法（#2815）：使用functools.singledispatch注册的分派函数可以正确生成文档。
• autodoc_typehints = 'description'（#7079）：如前所述，类型注解可放到对象描述中而非签名里。
• __wrapped__函数正确文档化（#7222）：结合unwrap_all()的引入，装饰器包裹的函数签名不再失真。
• 私有成员判定基于:meta private:（#6830）：docstring 的 info-field-list 中包含:meta private:即视为私有成员。
• 继承成员限定祖先类（#5923）：:inherited-members:可传类名参数。
• mock 性能回归修复（#7479，3.0.2）：修复 3.0.0 以来使用autodoc_mock_imports时构建变慢的问题。

3.2 标准域与索引

• glossary 重复词条警告（#6558）：重复的 glossary 词条会在构建时产生警告，帮助维护术语表质量。
• 通用对象（GenericObject）重复警告（#6558）：标准域中重复的通用对象同样触发警告。
• 索引页自动注册超链接目标（#3106）：genindex页面自动注册为超链接目标，便于交叉引用。
• genindex 优先展示 "main" 索引条目（#7220）。

3.3 HTML 输出与搜索

• html_scaled_image_link支持豁免（#7032）：为图片添加no-scaled-link类即可禁用该图片的缩放链接行为。该配置默认在 HTML 构建器中开启（sphinx/builders/html/init.py），并可被 epub 构建器覆盖。

• 按文档禁用全文搜索（#7025）：在文档文件级元数据中写:nosearch:，即可将该文档排除出全文搜索索引。实现于 sphinx/builders/html/init.py：

  if 'no-search' in metadata or 'nosearch' in metadata:

• 可覆盖 JS 分词器（#7293）：通过SearchLanguage.js_splitter_code可自定义搜索词切分逻辑，相关属性定义于 sphinx/search/init.py，分词器代码在构建搜索索引时被注入（sphinx/search/init.py）。

• 主题暗色模式代码块样式（#7142）：新增主题选项pygments_dark_style，用于在暗色模式下切换代码块的 Pygments 配色，主题配置读取见 sphinx/theming.py。

• 每个 desc 节点增加所属域 CSS 类（#7144）：HTML 输出中，对象描述节点会带有所属域名对应的 CSS class，便于定制样式。

• jQuery 安全升级（3.0.4，#7696）：HTML 输出内置 jQuery 从 3.4.1 升级到 3.5.1（安全修复）。

3.4 LaTeX 输出

• LaTeX 主题支持（实验性）（#6672）：为 LaTeX 输出引入主题机制，开启实验性的 LaTeX theming 能力。
• kbd角色的样式宏（#7005）：新增 LaTeX 样式宏以美化键盘按键角色。
• 中文文档在 XeLaTeX 下使用 babel（#7211）：使用 XeLaTeX 编译中文文档时切换到 babel 方案。
• Xindy 语言选项修复（3.0.2，#7414）：修复 LaTeX 索引生成中 Xindy 语言选项错误。

3.5 linkcheck 与构建器

• linkcheck 输出全部链接到output.json（#7103）：sphinx-build -b linkcheck现在会把所有检查过的链接写入output.json，便于脚本化分析。
• 同名多扩展名文档警告（#7324）：同一文档名对应多个不同扩展名源文件时，sphinx-build会发出警告。
• sphinx-build忽略bdb.BdbQuit（#7345/#7290）：调试器退出异常不再导致构建崩溃；输出目录为普通文件时给出友好处理而非崩溃。

3.6 apidoc 与事件

• --maxdepth在包文档间传播（#7314）：sphinx-apidoc的--maxdepth选项会通过包级文档逐层传递。
• SphinxDirective.get_source_info()/SphinxRole.get_source_info()：指令与角色可以获取当前解析的源文件与行号，实现位于 sphinx/util/docutils.py，便于扩展在警告信息中给出精确位置。
• object-description-transform新事件（#6830）：在对象描述被转换前触发，py domain 用它过滤 meta 字段（见上文）。

四、弃用 API 清单（Deprecated）

3.0 标记了一组 API 为弃用，第三方扩展作者应在升级时同步迁移。以下是完整清单及迁移方向：

五、逐版本 bug 修复要点（3.0.1–3.0.4）

3.0 系列后续补丁版本修复的问题值得升级时重点关注：

3.0.1（2020-04-11）

• term角色大小写敏感（前述破坏性变更）；
• 修复 py domain 中None引用产生 nitpicky 警告、None返回注解未转成 intersphinx 超链接的问题（#7428/#7445）；
• autodoc：autodoc_mock_imports导致ValueError（#7422）、__doc__返回非字符串对象时AttributeError（#7451）；
• HTML 主题：HTML5 doctype 下不再输出xmlns属性、模板链接转义（#7423/#7479 相关）。

3.0.2（2020-04-19）

• py domain：空元组类型注解IndexError（#7461）、keyword-only 参数被误标默认None（#7510）；
• 修复 3.0.0 以来 mock 导致构建变慢（#7479）；
• C 域属性解析与 C++ east-const 声明间距修复。

3.0.3（2020-04-26）

• C 域数组声明符解析（static / qualifiers / VLA）；
• autodoc：目标对象访问属性抛异常时崩溃（#7516）。

3.0.4（2020-05-27）

• autodoc：泛型类型的参数化类型显示两次（#7567）、Python 3.9 下系统 TypeVar 被展示（#7637）；
• OpenSSL FIPS 启用时 md5 失败（#7611）：Sphinx 的文件校验在 FIPS 模式下改用非 md5 方案；
• 发布包补回CODE_OF_CONDUCT（#7626）。

六、升级迁移清单

综合以上变更，从 Sphinx 2.x / 1.8 升级到 3.0 时建议按以下清单自查：

1. autosummary stub 文件：确认是否依赖旧版"不覆盖"行为，若是则设置autosummary_generate_overwrite = False；
2. 签名反斜杠：若域指令中依赖\\→\替换，设置strip_signature_backslash = True；
3. 交叉引用写法：检查numref_、parseInt_、say_hello_等尾随下划线链接，全部改用标准角色；token角色补上productionlist作用域；
4. 继承成员文档：若使用:inherited-members:+:special-members:，确认object成员缺失是可接受的；
5. 类型注解风格：如需autodoc_typehints = 'description'，同步评估autodoc_typehints_description_target与autodoc_typehints_format；
6. C 语言域：重写后解析更严格，新增的警告需要逐一核对；用户自定义属性请配置c_id_attributes/c_paren_attributes；
7. 弃用 API：对照上文弃用清单，替换第三方扩展中的已弃用调用；
8. 事件与节点：若扩展直接操作EventManager.listeners、desc_signature['first']或sphinx_cpp_tagname，必须适配新结构。

Sphinx 3.0 的源码结构变化（如autodoc的配置集中声明于 sphinx/ext/autodoc/_shared.py、autosummary的生成流程与配置注册位于 sphinx/ext/autosummary/init.py）也可以帮助扩展作者在阅读与调试时快速定位配置默认值与调用链。升级时建议以本清单结合 doc/changes/3.0.rst 原文逐条核对，先在小规模文档集上验证输出，再推广到全量构建。

• 文档
• 开发工具