执行摘要

• 一句话：修复两处 mkdocs 文档构建警告
• 推荐动作：不值得精读，属于常规文档维护。可作为 vLLM 文档构建规范的参考：链接到内部的类时，应使用实际定义模块（*.moe_runner.MoERunner）而不是未导出的父包路径；docstring 的 Attributes: 段落中，描述续行必须正确缩进，否则 griffe 会静默丢弃内容。提交中使用了 AI 辅助（Claude Code），作者声明已逐行检查，这可以作为 AI 辅助代码的审阅范例。

功能与动机

PR body 明确指出 mkdocs build 产生两条警告：griffe 无法从 mxfp6/base.py:21 解析 'name: description' 对，mkdocs_autorefs 无法在 moe_kernel_features.md 中找到交叉引用目标 MoERunner。作者在提交前检查过相关 PR 列表，确认没有重复工作。修复目标是让文档构建干净、链接可跳转。

实现拆解

步骤 1：修复 MoE 内核特性文档中的失效交叉引用

文件 docs/design/moe_kernel_features.md 中 all2all 后端表格的 naive 行，链接文本从旧的 layer.py（FusedMoE 重构前遗留）更新为 MoERunner，链接目标从 vllm.model_executor.layers.fused_moe.runner.MoERunner 改为 vllm.model_executor.layers.fused_moe.runner.moe_runner.MoERunner。原因是 runner/init.py 未重新导出 MoERunner，类实际定义在 runner/moe_runner.py 中；旧的链接目标无法解析，读者看到的只是纯文本。

步骤 2：修正 MxFp6LinearLayerConfig 的 docstring 缩进

文件 vllm/model_executor/kernels/linear/mxfp6/base.py 中，weight_quant_key 属性描述的续行 kMxfp6E2M3Static or kMxfp6E3M2Static. 原先没有缩进，导致 griffe 把该行当作新属性解析，weight_quant_key 的描述从文档中丢失。修正为与描述正文对齐的 8 空格缩进后，griffe 能正确解析两个属性及其完整描述。

测试与验证

作者在分支上运行 mkdocs build 验证：griffe 正确提取 weight_quant_key 与 activation_quant_key 两个属性；autorefs 解析出的链接指向 runner/moe_runner.py 且锚点存在。本次为纯文档变更，无运行时行为变化，因此不涉及模型评测或单元测试。

关键文件：

• vllm/model_executor/kernels/linear/mxfp6/base.py（模块 量化内核；类别 source；类型 documentation）: 这是两个警告之一的来源：MxFp6LinearLayerConfig 的 docstring 缩进错误导致 griffe 解析失败。修复后属性描述恢复显示。
• docs/design/moe_kernel_features.md（模块 设计文档；类别 docs；类型 documentation）: MoE 内核特性设计文档中 naive 后端的 MoERunner 交叉引用指向了未导出该类的 fused_moe.runner 包，链接无法解析且文案过时。修复后链接可跳转。

关键符号：未识别

关键源码片段

vllm/model_executor/kernels/linear/mxfp6/base.py

这是两个警告之一的来源：MxFp6LinearLayerConfig 的 docstring 缩进错误导致 griffe 解析失败。修复后属性描述恢复显示。

# 修复前：docstring 中 `weight_quant_key` 描述的续行（kMxfp6E2M3Static...）没有缩进，
# griffe 会把它解析成一个新属性，导致该描述从渲染文档中丢失。
# 修复后：续行缩进为与描述正文对齐，griffe 能正确解析两个属性及其完整描述。
@dataclass
class MxFp6LinearLayerConfig:
    """Configuration for an MXFP6 linear layer.
​
    All MXFP6 layers share the same structure: packed uint8 weights (2 FP4 values per
    byte) and per-block weight scales (group size 32).
​
    Attributes:
        weight_quant_key: Identifies the weight quantization format. Can be
            kMxfp6E2M3Static or kMxfp6E3M2Static.
        activation_quant_key: Identifies the activation quantization format,
            or `None` when activations must not be quantized.
    """
​
    weight_quant_key: QuantKey
    activation_quant_key: QuantKey | None = None

评论区精华

该 PR 的 review 过程没有技术讨论：claude[bot] 自动回复说明 fork 分支禁用了自动化 review，仓库维护者 DarkLight1337 直接批准（APPROVED）。mergify[bot] 在 issue 评论中提供了 ReadTheDocs 预览链接用于验证文档效果。

• 暂无高价值评论线程

风险与影响

• 风险：由于这是纯文档变更，运行时风险为零。剩余风险集中在文档可持续性上：
  1) docs/design/moe_kernel_features.md 中的交叉引用依赖 moe_runner.py 中的类路径，未来若 MoE runner 再次重构或重命名，链接会再次失效；
  2) base.py 中的 docstring 依赖 griffe 对缩进的解析，后续编辑若不注意缩进，同样会重复出现 'name: description' 解析失败。此外，该文件位于 vllm/model_executor/kernels/linear/mxfp6 量化路径上，虽本次只改注释，但未来改动时仍需遵循文档解析规则。
  • 影响：影响范围限于文档构建和阅读体验：消除了 mkdocs build 的两条警告，使 CI 构建输出更干净；修复后的文档链接可正确跳转到 MoERunner 的 API 页面，MxFp6LinearLayerConfig 的 weight_quant_key 属性描述恢复显示。对终端用户、模型推理路径、性能均无影响。对团队而言，这是低风险的文档维护，且为后续文档构建的稳定性提供了一个小样本。
  • 风险标记：文档链接依赖类路径, docstring 缩进解析敏感

关联脉络

• 暂无明显关联 PR