Use semver compatible links to dependencies
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.2k
- Forks
- 232
- Avg merge
- 11h 35m
- Merged PRs (30d)
- 60
Description
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:
- The exact kind of a type is part of the url, so while e.g. changing a
structto anenumis a non-breaking change to code, it will result in a link to the item becoming a 404 (https://github.com/rust-lang/rust/issues/55160) - Re-exports don't exist in the file tree, as an example consider these two versions of a crate:
// Version 1.0.0
pub struct Foo;
// Version 1.0.1 - A semver compatible change to move the canonical location and leave a re-export behind
pub mod foo { pub struct Foo; }
pub use foo::Foo;
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:
target/doc/foo
├── all.html
├── index.html
├── sidebar-items.js
└── struct.Foo.html
target/doc/foo
├── all.html
├── foo
│ ├── index.html
│ ├── sidebar-items.js
│ └── struct.Foo.html
├── index.html
└── sidebar-items.js
(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).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the docs.rs documentation build's --extern-html-root-url handling and the Rustdoc behavior described in issue 55160. Review the struct-to-enum and re-export examples, then identify other semver compatibility failures and assess whether Rustdoc can guarantee stable links. Done means a documented feasibility decision and a defined path for using constraint-based URLs, if viable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100