Provide a way to interpolate crate version in html_root_url

6ae43b4
Opened by David Tolnay at 2025-03-14 10:08:09

In Serde we work around this by having a reminder in Cargo.toml to update the html_root_url when releasing a new version. https://github.com/serde-rs/serde/commit/dc7ab2696a14fe5ca219ac09f8496bdc613ff602

[package]
version = "1.0.8" # remember to update html_root_url

#![doc(html_root_url = "https://docs.rs/serde/1.0.8")]

This is annoying and easily falls out of sync. For example mio 0.6.8 docs point to version 0.6.1: https://github.com/carllerche/mio/issues/613.

There should be a way to keep these synchronized automatically.

  1. Macros in attributes would neatly solve this, just sayin'.

    Alex Burka at 2017-05-30 16:42:31

  2. I recently implemented --extern-version argument to rustdoc and cargo for this purpose. I don't think this patches should be in rust or cargo but I am planning to solve all external crate links in docs.rs with this patches. Docs.rs is not using this compiler yet, building rustc for all tier one platforms requires a lot of effort.

    Hopefully docs.rs will set html_root_url automatically for all crates soon and it will help maintainers to not care about html_root_url.

    Onur Aslan at 2017-05-31 13:11:23

  3. If I'm reading this commit correctly, it appears that docs.rs does it now. This is not documented anywhere though, as far as I can see.

    Nadrieril at 2020-03-19 17:00:46

  4. Apparently that's not enough to not need html_root_url sadly; that seems to depend on https://github.com/rust-lang/rust/issues/42301

    Nadrieril at 2020-03-19 17:19:26

  5. I may not have a good understanding of the issue but I think what we would like is the ability to write (something like):

    #![doc(html_root_url = "https://docs.rs/serde/{version}")]

    Where {version} refers to the value in Cargo.toml (which is available in macros c.f. the clap crate), so it might need to be (say) {Cargo.toml::version} to indicate the source without the compiler needing to just "know" it and thus Cargo.toml being somewhat "magical" (this assumes we may want/need other possible distinguishable sources). Of course #![doc("link")] is an attribute not a macro so this method maybe more easily suggested than coded. Once this substation mechanism is added it may well find a lot of uses elsewhere. Or I maybe talking tosh :(.

    Rod at 2025-03-14 10:08:09