构建脚本辅助工具，用于将从当前crate的源目录下的媒体和资源文件复制到rustdoc的目标输出目录。

查看GitLab-Pages上的文档： https://p1892.gitlab.io/rustdoc-assets

lib.rs:

构建脚本辅助工具，用于将从当前crate的源目录下的媒体和资源文件复制到rustdoc的目标输出目录。

当前rustdoc不支持将媒体文件复制到文档输出目录。图片只能作为在线资源引用。

这个crate可以解决这个问题。将 copy_assets_folder() 函数调用添加到您的crate的 build.rs 构建脚本中。这将把指定的源目录复制到rustdoc输出目录。

来源： https://mrh.io/cargo-build-images-in-rust-docs/

示例

考虑以下crate "foo" 的目录结构

.
├── build.rs
├── Cargo.toml
├── changelog.md
├── doc
│   └── img
│       └── it-works.svg
├── readme.md
├── src
│   └── lib.rs
└── target

在这个例子中，使用 cargo doc 命令将在 ./target/doc/foo 创建API文档。我们希望在crate文档目录中包含文件 doc/img/it-works.svg。

为此，在您的 Cargo.toml 文件中添加对 rustdoc-assets 的构建依赖

[build-dependencies]
rustdoc-assets = "0.2"

在 build.rs 中执行以下操作

rustdoc_assets::copy_assets_folder("doc/img");

这将把 ./doc/img 复制到 ./target/doc/foo/img。在rustdoc注释中，可以通过HTML标签引用这些图片，如下所示

/// <div align="center">
/// <img src="img/it-works.svg" width="200" />
/// </div>

来源： 维基百科 (CC)

更新 2021-10-16

在Rust 1.55中，cargo doc现在在生成文档之前会自动清理target/doc目录。然而，rustdoc-assets使用构建脚本，并且只在调用cargo build/check时执行。如果之后执行cargo doc，后续文件夹会被删除。目前我还没有比在cargo doc之后至少再运行一次cargo check更好的解决方案。