Crate rustdoc_assets

Build script helper which copies media and assets from a source directory below your current crate to the target output directory of rustdoc.

rustdoc currently does not support copying media files to the documentation output directory. Pictures can only be included if they can be referenced as an online resource.

This crate mitigates the problem. Add a call to copy_assets_folder() to the build script build.rs of your crate. This will copy the specified source directory to the rustdoc output directory.

Source: https://mrh.io/cargo-build-images-in-rust-docs/

Example

Consider the following directory structure of crate “foo”:

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

In this example, a call to cargo doc would create the API documentation in ./target/doc/foo. We want to include the file doc/img/it-works.svg in the crate documentation directory.

To do this, add a build dependency to rustdoc-assets in your Cargo.toml:

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

In build.rs do:

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

This will copy ./doc/img to ./target/doc/foo/img. In the rustdoc comment the images can then be referenced through an HTML-tag as follows:

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

Source: Wikipedia (CC)

Update 2021-10-16

In Rust 1.55 cargo doc now auto-cleans the target/doc-directory before generating the documentation. However, rustdoc-assets uses the build script and only executes during calls to cargo build/check. If cargo doc is executed afterwards the folders subsequently get removed. I currently do not have a better solution than to at least run cargo check one more time after cargo doc.

Functions

copy_assets_folder

Copy media files (images, etc) to your rustdoc output directory.