[rustdoc, request] Please bundle local relative resources (favicon, logo, whatever)

[jnqnfe]

For some of my crates I have a favicon and logo within the repo but have to point to them via public links like this:

#![doc(html_logo_url = "https://github.com/jnqnfe/pulse-binding-rust/raw/master/logo.png",
       html_favicon_url = "https://github.com/jnqnfe/pulse-binding-rust/raw/master/favicon.ico")]

What I would love (and have long wanted) is if I could simply refer to the files with a relative path like this...:

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

...and cargo doc would then bundle them into the set of generated documentation files, such that when viewing the documentation offline locally, these resources are loaded from the target/doc/ directory, and for the docs.rs copy, docs.rs would serve them along with the rest of the page components.

This would include the following advantages:

• The favicon and logo would actually get loaded properly when viewing documentation offline. (It's very annoying that they don't, and loading them once at some point when you are online is not sufficient to subsequently ensure they are shown from cache in my experience).
• Helps ensure in future that a change such as a move of the repo from github to gitlab, or move/rename of the files within the master copy of the public repo, does not break display of these items for older published versions of crates due to broken links.
• Helps avoid in future trouble replacing favicon/logo images with new ones for new releases without replacing the older copies for older versions of the documentation, without making a mess of maintaining multiple versions of the file within the repo.
• Helps alleviate any privacy concerns from loading such resources while online but reading local documentation.

Perhaps this could be applied to all such local relatively referenced image resources (others too?), not just favicon and logo, to cover situations where repos include images to embed in docs.

[jyn514]

Related: #75964, #51625

[andrewbanchich]

This would be fantastic. It's been very annoying because we use a private GitHub repo, so our offline documentation just shows broken images. That also means we can't even confirm the links are correct before committing.

[jsha]

Copying over from my comment at #102083:

@Nemo157 pointed out at rust-lang/docs.rs#1853 (comment) that rustdoc offers two attributes, html_logo_url, and html_favicon_url, which are commonly used to embed image tags pointing to URLs on a different site than the documentation is served on:

https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#html_logo_url
https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#html_favicon_url

For reasons of privacy, performance, and offline access, it would be nice if this attribute could point at a file shipped with the crate itself, and copied from there into the documentation.

Proposal: if one of these attributes contains a URL that does not start with http:, https: or /, rustdoc should treat it as a file path relative to the crate root. Rustdoc should copy that file into the doc directory, and generate documentation that references the local file for the logo/favicon.

One downside: this means every download of the crate source for builds also has to download the logo and favicon, which are only needed for documentation.

Note that any solution that doesn't bundle the images into the crate runs into problems because (a) cargo doc builds docs for dependencies, and often only has the packaged crate for those and (b) docs.rs only has access to the packaged crate when building docs.

[jyn514]

Bundling images for dependencies will massively increase the size of the .rlib metadata, even when building without rustdoc, which means this would be a giant compile-time hit across the ecosystem. Bundling would be have to be done by rustc itself, because rustdoc can't generate metadata.

[jyn514]

Note that any solution that doesn't bundle the images into the crate runs into problems because (a) cargo doc builds docs for dependencies, and often only has the packaged crate for those and (b) docs.rs only has access to the packaged crate when building docs.

I don't understand why this is a problem. With your proposal, where this only supports file:// urls, Rustdoc can't access the assets regardless unless they're in the crates.io package. So I don't see how including the assets in the metadata helps; the metadata is created at the same time that docs.rs is documenting the main crate.

[jsha]

I don't understand why this is a problem. With your proposal, where this only supports file:// urls, Rustdoc can't access the assets regardless unless they're in the crates.io package. So I don't see how including the assets in the metadata helps; the metadata is created at the same time that docs.rs is documenting the main crate.

Right, I was talking about including assets in the crates.io package, not the .rlib metadata.