为 Bevy 定制 rustdoc 文档页：用 docs-rs 扩展为类型注入 `Component`/`Resource` 等核心 Trait 标签

Bevy 在 docs-rs 目录中维护了一套针对 rustdoc 输出的扩展模板与样式，用于在其文档站点上为类型页面自动附加 Bevy ECS 核心 Trait 的识别标签（例如 Component、Resource、Plugin、Asset、Event），让读者无需展开庞大的 trait 实现列表就能一眼判断某个类型在 ECS 架构中的角色。本文以 docs-rs/README.md 与 trait-tags.html 为骨架，结合仓库根 Cargo.toml 中的 docs.rs 元数据与 bevy_ecs 源码，讲清这套扩展的原理、配置方法与本地验证方式，同时给出你在自己的第三方 crate 中复刻同样能力的完整操作步骤。

这套扩展解决什么问题

rustdoc 生成的 API 文档会按类型列出其实现的所有 trait，但由于 ECS 框架中存在大量 trait，页面往往冗长。以 bevy_ecs 为例，一个类型通常同时实现了几十个 trait，其中 Component、Resource、Event、Message 等决定了它在 Bevy 中「能干什么」，却容易淹没在 Debug、Default、反射类 trait 之中。

Bevy 的思路是：借助 rustdoc 的 --html-after-content 钩子在文档页末尾追加一段 HTML，用 JavaScript 扫描页面中已声明的 trait 实现，并把命中白名单（如 Component）的项渲染成页面标题下方的彩色小标签，同时配上指向对应 trait 文档页的链接。这样类型页面会以「xx 类型 + Component 标签」的形式呈现，属于该类型的 trait 语义变得一目了然。

这一脚本与样式位于 docs-rs/trait-tags.html，目前标记的 Bevy 核心 trait 白名单如下：

Plugin、PluginGroup、Component、Resource、Asset、Event、Message、ScheduleLabel、SystemSet、SystemParam、Relationship、RelationshipTarget、Scene、SceneList、Template、FromTemplate、SceneComponent

注意白名单数组的顺序（见 trait-tags.html）决定标签在列表中的排序，插入新标签时应考虑语义从属关系。

脚本实现原理：在文档加载后改写 DOM

rustdoc 的 --html-after-content 会在每页正文结束处注入自定义内容，Bevy 在此注入 <script> 与 <style>。其核心执行流程如下（对应 trait-tags.html）：

1. 收集 trait 实现：通过 querySelectorAll('#trait-implementations-list .impl .code-header, #blanket-implementations-list .impl .code-header') 找出页面上所有直接实现与 blanket 实现块；对每个 header 的文本先去泛型（递归地删除 <...>），再按空格切分取出第二个 token 作为 trait 名，例如 impl Component for Sprite 会被解析出 Component。
2. 过滤白名单并保留链接：在结果中保留命中 bevyTraits 白名单的项，同时从 header 的 <a> 子元素中提取 href（锚点 href 需包含 trait.<名称>.html），使标签可跳转到对应 trait 文档页。
3. 处理语义包含关系：脚本对标签做了去冗余处理——Resource: Component {} 意味着 Resource 已是组件，因此当类型同时实现二者时删除 Component 标签只保留 Resource；同理 SceneComponent 隐含 Component、FromTemplate 隐含 Template（见 trait-tags.html）。
4. 区分可变与不可变（Immutable）类型：脚本扫描 .trait-impl.associatedtype .code-header，若发现存在 type Mutability = Immutable 的实现，则把标签改写为 Immutable Component 或 Immutable Resource（见 trait-tags.html）。脚本注释也坦承这是对完整 associated type 检查的简化替代方案（受限于 docs.rs 页面布局）。
5. 渲染标签：找到 .main-heading h1 作为锚点，新建一个 div.bevy-tag-container 并逐个插入 <a class="bevy-tag ..."> 元素；标签文案会被转成 kebab-case 拼进 class（例如 Immutable Component → immutable-component-tag）。

样式部分则通过 CSS 变量 --tag-color 为每类标签赋予区分度较高的颜色，其中特意用 oklch() 颜色空间定义（例如 component-tag、immutable-component-tag 为 oklch(50% 27% 80)，resource-tag 系为 oklch(50% 27% 110)），标签为带圆角（border-radius: 0.75rem）的胶囊样式（见 trait-tags.html）。

仓库内的启用方式：[package.metadata.docs.rs]

Bevy 在仓库根 Cargo.toml 的 [package.metadata.docs.rs] 段中集中声明了整套文档构建参数：

[package.metadata.docs.rs]
# This cfg is needed so that #[doc(fake_variadic)] is correctly propagated for
# impls for re-exported traits. See https://github.com/rust-lang/cargo/issues/8811
# for details on why this is needed. Since dependencies don't expect to be built
# with `--cfg docsrs` (and thus fail to compile) we use a different cfg.
rustc-args = ["--cfg", "docsrs_dep"]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
rustdoc-args = [
  "-Zunstable-options",
  "--generate-link-to-definition",
  "--generate-macro-expansion",
  # Embed tags to the top of documentation pages for common Bevy traits
  # that are implemented by the current type, like `Component` or `Resource`.
  # This makes it easier to see at a glance what types are used for.
  "--html-after-content",
  "docs-rs/trait-tags.html",
]
all-features = true

其中两个细节值得注意：

• --cfg docsrs_dep 与 docs.rs 的差异：docs.rs 官方平台默认以 --cfg docsrs 构建，会让诸如 #![cfg_attr(docsrs, feature(doc_cfg))] 的代码生效；但 Bevy 是依赖方，不能假定依赖自身的构建过程带上 docsrs。因此在 Cargo.toml 里改用自定义 cfg docsrs_dep，并在各 crate 的 lib.rs 中统一通过 any(docsrs, docsrs_dep) 声明特性开关。例如 crates/bevy_ecs/src/lib.rs 中：

  #![cfg_attr(
      any(docsrs, docsrs_dep),
      expect(
          internal_features,
          reason = "rustdoc_internals is needed for fake_variadic"
      )
  )]
  #![cfg_attr(any(docsrs, docsrs_dep), feature(rustdoc_internals))]
  #![cfg_attr(docsrs, feature(doc_cfg))]
  

  同样的模式出现在 bevy_app、bevy_render、bevy_reflect、bevy_math、bevy_state 等 crate 的 lib.rs 中，其目的是启用 nightly 的 rustdoc_internals 特性以支持 #[doc(fake_variadic)]（用于为被 re-export 的 trait 正确传播变长参数文档，关联 cargo 议题 #8811）。由于日常编译时不会定义该 cfg，普通 cargo build 不受影响，编译期会通过 lints.rust 段做 check-cfg 校验以免触发 unexpected_cfgs 警告。
• rustdoc 相关的扩展选项：-Zrustdoc-scrape-examples、--generate-link-to-definition 与 --generate-macro-expansion 进一步增强了文档的示例引用与定义跳转能力；all-features = true 保证开启全 feature 构建文档。

在第三方 crate 中复刻标签扩展

若你自己的 crate 也想让文档页显示这类核心 trait 标签，docs-rs/README.md 给出了完整的接入步骤。

1. 复制扩展文件并声明 lint

先将仓库中的 docs-rs 目录（至少包含 trait-tags.html）复制到你的项目，然后在 Cargo.toml 中加入如下配置（来自 docs-rs/README.md）：

[package.metadata.docs.rs]
rustc-args = ["--cfg", "docsrs_dep"]
rustdoc-args = [
    "--cfg", "docsrs_dep",
    "--html-after-content", "docs-rs/trait-tags.html",
]

[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(docsrs_dep)'] }

这里 --html-after-content docs-rs/trait-tags.html 让 rustdoc 在每个文档页正文之后注入标签脚本；--cfg docsrs_dep 与根 Cargo.toml 的用法保持一致；lints.rust.unexpected_cfgs 则把 cfg(docsrs_dep) 声明进 check-cfg，避免 rustc 对未被识别 cfg 报 unexpected_cfgs 警告。

2. 本地构建验证

在不借助 docs.rs 的情况下，用 rustdoc/rustc 环境变量等价地传入配置（来自 docs-rs/README.md）：

RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html --cfg docsrs_dep" RUSTFLAGS="--cfg docsrs_dep" cargo doc --no-deps --package <package_name>

构建完成后，用浏览器打开 target/doc/<package_name>/index.html 并进入任一同时实现白名单内 trait 的类型页，即可在页面标题旁看到对应彩色标签。需要说明的前提是：由于该扩展依赖 rustdoc_internals、--generate-link-to-definition 等 nightly 特性，这类构建通常需要 nightly 工具链支持。

3. 按需改写脚本内容

复制扩展后，你可以直接编辑 trait-tags.html 做定制：增删 trait-tags.html 中 bevyTraits 数组的成员以决定标记哪些 trait；调整末尾 <style> 段中的 --tag-color（以 oklch() 定义）与 border-radius 等来匹配自家品牌配色；对具有「A 蕴含 B」语义的 trait 对，参照脚本中 Resource→Component 的去冗余逻辑增加对应处理，保持标签列表的简洁。

底层 trait 定义与标签的对应关系

要让标签扩展真正命中页面，依赖的是 rustdoc 能在目标类型页面上渲染出对应 trait 的 impl 块。从源码层面可以把白名单标签与其真实定义位置对应起来，便于你在自己的 crate 中复用同一套命名：

• Component：定义于 crates/bevy_ecs/src/component/mod.rs，约束为 Send + Sync + 'static，并带有 STORAGE_TYPE 常量、type Mutability: ComponentMutability 关联类型及若干生命周期钩子（on_add/on_insert/on_discard/on_remove）。脚本中「type Mutability = Immutable 时改写为 Immutable 标签」的逻辑，正是基于该 trait 的 Mutability 关联类型设计。
• Resource：定义于 crates/bevy_ecs/src/resource.rs，pub trait Resource: Component {}——源码中它本身就是 Component 的子 trait，这解释了脚本为何在两者同时命中时只保留 Resource 标签（避免标签冗余）。
• Message：定义于 crates/bevy_ecs/src/message/mod.rs，约束为 Send + Sync + 'static，属于 ECS 通信体系中的一类关键 trait。

可见，标签扩展的价值在于把「源码中通过继承/关联类型表达的语义关系」具象化为文档页顶部人人可读的视觉标记；若你计划为其他 ECS 类 crate 复刻此方案，同样应先梳理自己核心 trait 之间的包含关系，再参照 findImplementedBevyTraits 的过滤逻辑编写脚本。

小结

通过 --html-after-content 注入脚本 + CSS，Bevy 用很小的成本显著提升了 rustdoc 文档的类型辨识度：Component/Resource/Plugin 等核心角色被渲染成页首彩色标签，并保留跳转链接。本文已完整覆盖三层落地路径——Be 仓库自身的 [package.metadata.docs.rs] 配置、docs.rs 平台上的实际行为（docsrs 与 docsrs_dep 的区分）、以及第三方 crate 一键复刻的 Cargo 配置与本地验证命令。在你的项目根 Cargo.toml、扩展脚本 trait-tags.html 与底层 trait 源码（component/mod.rs、resource.rs）之间对照阅读，即可完整理解并迁移这套做法。