You do not need html_root_url

It's somewhat common to have lines like this in crates:

// Cargo.toml
[package]
name = "foo"
version = "0.1.2" # Also update html_root_url in lib.rs when bumping this

// lib.rs
#![doc(html_root_url = "https://docs.rs/foo/0.1.2")]

For a long time I was quite annoyed by such version duplication. But it turns out that you do not need html_root_url on modern toolchains!

See the following links for more information:

2 Likes

I thought that attribute was made redundant back when they started linking to docs.rs by default?

Setting html_root_url is still immensely useful when building crate documentation locally. If building with cargo doc --no-deps types are not linked unless the source crate specifies html_root_url.

Possible solutions like -Zrustdoc-map are still unstable. Until then, keeping the attribute still is useful and crates like version-sync ensures that all version numbers are kept in sync. After all, there might be more places with version duplication.

https://crates.io/crates/version-sync

3 Likes

I got tired of forgetting to update the version number so I created a tiny crate called version-sync which will detect if the attribute is out of date.

I've since then also managed to automate my release process so that the attribute is updated by a script. See prepare-release.yml if you're curious.

It would of course be great if the attribute could be deprecated completely.

It would be nice if usage for docs.rs could be deprecated/made unnecessary, but it still has use for when documentation is special built not on docsrs (say, for exotic platform(s), or closed-source internal registries.)