rust-lang / rust-lang/docs.rs

Use semver compatible links to dependencies

Open
#1,055 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-builds C-enhancement S-blocked
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:

  1. The exact kind of a type is part of the url, so while e.g. changing a struct to an enum is 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)
  2. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.