如何只在主 crate 文档中展示被重导出的子 crate？

2026-11-06数据小许

结论

Rustdoc 没有直接判断 crate 是单独生成文档，还是作为依赖由主 crate 通过 #[doc(inline)] 重导出的条件。可以用 Cargo feature 区分这两种构建：主 crate 依赖子 crate 时启用专用 feature，子 crate 在 docs.rs 单独构建时则不启用。子 crate 可以在该 feature 未启用时为公开 API 添加 #[doc(hidden)]，并在 crate 级文档中说明如何通过主 crate 使用它。

#[doc(inline)] 会将依赖 crate 的文档内联到主 crate 的重导出位置；#[doc(hidden)] 会隐藏标记的项目。应按需将隐藏属性加到子 crate 的公开模块和项目上。若直接给项目添加 #[doc(hidden)]，它在主 crate 的文档中也会被隐藏。详情见 Rustdoc 关于重导出的说明和 doc 属性说明。

配置 feature

在子 crate 中定义一个非默认 feature 作为标记，例如 inline-docs：

# mycrate_one/Cargo.toml
[features]
inline-docs = []

主 crate 依赖子 crate 时启用这个 feature，再用主 crate 自己的 feature 控制是否包含该依赖：

# mycrate/Cargo.toml
[dependencies]
mycrate_one = { version = "1", optional = true, features = ["inline-docs"] }

[features]
one = ["dep:mycrate_one"]

主 crate 的 src/lib.rs 保留重导出：

#[cfg(feature = "one")]
#[doc(inline)]
pub extern crate mycrate_one as one;

子 crate 在 inline-docs 未启用时隐藏公开 API。下面以公开模块为例：

//! 请通过 [`mycrate`](https://docs.rs/mycrate) 使用此 crate。

#[cfg_attr(not(feature = "inline-docs"), doc(hidden))]
pub mod api;

其他公开模块、类型和函数也需要类似处理；也可以把 API 集中到少数公开模块中统一控制。主 crate 启用 inline-docs 后，这些项目不会带有 doc(hidden)，可以随 #[doc(inline)] 出现在主 crate 的文档里。子 crate 单独构建且未启用该 feature 时，相关 API 会从文档中隐藏，页面仍可保留 crate 级说明。

配置 docs.rs

每个 crate 都可以通过自己的 [package.metadata.docs.rs] 配置指定 docs.rs 构建时启用的 feature；all-features 默认值为 false。应确保子 crate 单独构建文档时不启用 inline-docs，同时主 crate 构建文档时启用对应的 one feature。例如：

# mycrate_one/Cargo.toml
[package.metadata.docs.rs]
all-features = false

# mycrate/Cargo.toml
[package.metadata.docs.rs]
features = ["one"]

docs.rs 的 feature 配置见构建元数据说明。如果子 crate 的默认 feature 或 docs.rs 配置启用了 inline-docs，独立文档也会显示 API，因此需要检查实际启用的 feature 组合。

注意事项

这套配置通过 feature 控制文档内容，rustdoc 不会自动检测 crate 是否处于被重导出的上下文。doc(hidden) 也会影响所有未启用 inline-docs 的构建，因此应根据项目需要分别设计运行时依赖、功能 feature 和文档 feature。还应检查每个子 crate 的 docs.rs 页面和主 crate 的内联页面，确认隐藏范围和链接符合预期。