5 releases
0.2.1 | Nov 19, 2022 |
---|---|
0.2.0 | Dec 4, 2021 |
0.1.2 | Oct 16, 2021 |
0.1.1 | Dec 18, 2020 |
0.1.0 | Dec 17, 2020 |
#455 in Build Utils
9KB
52 lines
Build script helper which copies media and assets from a source directory below your current crate to the target output directory of rustdoc.
Check out the documentation on GitLab-Pages: https://p1892.gitlab.io/rustdoc-assets
lib.rs
:
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.
Dependencies
~100KB