生成 rustdoc 时如何使用本地文件作为 crate 徽标？

Question

It is possible to set both the favicon and the logo of the rustdoc for a crate by using:

• #.[doc(html_favicon_url = "<url_to>/favicon.ico")]
• #.[doc(html_logo_url = "<url_to>/logo.png")]

as documented here .

However I do not want to upload my logo publicly and would therefore like to automatically include these files in /target/doc and reference them from there.

Currently I have put the respective data urls (base64 encoded) into these fields and it works fine, but it enormously bloats the source file where these attributes are set.

I know I could just copy the images into target/doc after generating the documentation using a script and then reference them using the relative url, but I would like to avoid this, so that I can still generate the documentation using cargo doc .

Edit

The suggestion from the comment to set the --output flag of rustdoc using rustdocflags in .cargo/config.toml also did not work, because it leads to error: Option 'output' given more than once . Apart from that, it is not suited for me, because (at least as far as I understand) I can only give absolute paths there, whereas I would need a solution using relative paths for the images, because I have those images stored in a subdirectory of the cargo root directory, to allow for easy transfer to another system using git, etc.

Answer 1

Thanks to the latest comment from eggyal I finally figured out how to do this:

In my build.rs I copy the files to target/doc/ :

fn main() {
    // Copy the images to the output when generating documentation
    println!("cargo:rerun-if-changed=assets/doc");
    std::fs::copy("assets/doc/logo.ico", "target/doc/logo.ico").expect("Failed to copy crate favicon when building documentation.");
    std::fs::copy("assets/doc/logo.png", "target/doc/logo.png").expect("Failed to copy crate logo when building documentation.");
}

and then I just had to make sure, to use an absolute path when referencing them, like so:

#![doc(html_favicon_url = "/logo.ico")]
#![doc(html_logo_url = "/logo.png")]

In general it would be better to read the CARGO_TARGET_DIR environment variable instead of hardcoding target/doc , but this is not yet available in build scripts.