Use semver compatible links to dependencies #1055
Labels
A-builds
Area: Building the documentation for a crate
C-enhancement
Category: This is a new feature
S-blocked
Status: marked as blocked ❌ on something else such as an RFC or other implementation work.
Currently when we build documentation we pass a flag like
--extern-html-root-url foobar=https://docs.rs/foobar/1.0.0
for each dependency with the exact version of the dependency used. This means if the dependency releases a new version compatible with the version constraint, all the links to it from the dependent crate will still go to the old version.To avoid this we could pass semver-constraint urls like
--extern-html-root-url foobar=https://docs.rs/foobar/^1.0.0
(based on the actual constraint specified), then links will automatically go to the latest compatible version of the docs.The biggest blocker to doing so is getting guarantees from Rustdoc that intra-doc-links generated for one version of a crate will still be valid in all semver-compatible later versions of the crate. A couple of issues currently cause this to not be true:
struct
to anenum
is a non-breaking change to code, it will result in a link to the item becoming a 404 (Usename.namespace.html
as the canonical URL, notkind.name.html
rust#55160)Looking at the filetree of the built docs we can see that a link to the old canonical location of
foo/struct.Foo.html
will be a 404 in the new version:(There may be more issues, these are just what was linked to me by @jyn514 and the first thought I had of what might go wrong. The first step of actually working on this if it's worth it would be identifying all the potential issues and working out whether it's possible/worthwhile trying to get this guarantee out of Rustdoc).
The text was updated successfully, but these errors were encountered: