`rust-docs`/`rustup doc` extremely frequently links to `doc.rust-lang.org` instead of local files, makes offline browsing experience very poor
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.1k
- PR merge metrics
- PR metrics pending
Description
Prefacing this by saying I don't know how to properly triage this. It's likely that I haven't found all of the different cases where this happens.
Problem: rustup doc is severely broken when viewed without an internet connection, due to tons of links incorrectly linking to doc.rust-lang.org instead of the locally installed documentation files.
All of this was found on Rust 1.80.1 on the x86_64-unknown-linux-gnu toolchain, but I'd expect other targets to fare similarly.
I will mainly use examples I found browsing rustup doc --std, but this applies just as much to core, alloc, etc. It's possible it also applies to some of the mdbooks, but I'd consider that a separate problem.
The issue has multiple parts:
sourcelinks extremely often do not link to the local files.
Example: thesourcelink ofstd::alloc(module) correctly links to the local files. Thesourcelink ofstd::alloc::alloc(function) links todoc.rust-lang.org.
Rudimentary grepping fordoc.rust-lang.orglinks in the HTML files of/std/seem to suggest that this happens in the vast majority of cases (so many I had to start filtering out/src/links when grepping for other cases). It might be related to things like re-exports or other item-path/visibility related things. (see below)- Some item links such as re-exports link to
doc.rust-lang.orginstead of local files.
Example: The re-export ofcore::arch::*instd::archlinks todoc.rust-lang.orginstead of the local files forcore. - Some relative links in doc comments link to
doc.rust-lang.orginstead of local files.
Example: In the doc comments forstd::alloc::Global, the link toAllocator(written in-source as[`Allocator`]) correctly links to the local file for the allocator trait, but the link tofree functions in alloc(written in-source as[free functions in `alloc`](self#functions)) links todoc.rust-lang.org. - Some documentation explicitly links to
doc.rust-lang.orginstead of local files for things like links to the nomicon or the reference.
Example: Documentation tostd::ffi::c_voidexplicitly links tohttps://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs. This is of course more understandable, since that's not a link generated by rustdoc, but arguably these links should also instead link to the local copy of the nomicon, though finding and fixing these links will probably require some manual effort.
Other than the countless number of source links that go to doc.rust-lang.org instead of the local /src/ files, here's a (deduplicated) list of all the non-local links in the HTML documentation for std only:
$ rg -oNI 'doc.rust-lang.org/.*?\.html' std/**/*.html | rg -v '/src/' | sort -u
doc.rust-lang.org/1.80.1/alloc/alloc/index.html
doc.rust-lang.org/1.80.1/alloc/index.html
doc.rust-lang.org/1.80.1/core/arch/index.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/cpuid/struct.CpuidResult.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m128bh.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m128d.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m128.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m128i.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m256bh.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m256d.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m256.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m256i.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m512bh.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m512d.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m512.html
doc.rust-lang.org/1.80.1/core/core_arch/x86/struct.__m512i.html
doc.rust-lang.org/1.80.1/core/error/struct.Source.html
doc.rust-lang.org/1.80.1/core/ffi/c_str/struct.Bytes.html
doc.rust-lang.org/1.80.1/core/ffi/index.html
doc.rust-lang.org/1.80.1/core/macro.assert_unsafe_precondition.html
doc.rust-lang.org/1.80.1/core/macro.panic.html
doc.rust-lang.org/1.80.1/core/num/index.html
doc.rust-lang.org/1.80.1/core/prelude/rust_2021/index.html
doc.rust-lang.org/1.80.1/core/prelude/rust_2024/index.html
doc.rust-lang.org/1.80.1/core/ptr/metadata/traitalias.Thin.html
doc.rust-lang.org/1.80.1/core/slice/sort/struct.TimSortRun.html
doc.rust-lang.org/1.80.1/core/slice/struct.GetManyMutError.html
doc.rust-lang.org/1.80.1/core/slice/trait.SlicePattern.html
doc.rust-lang.org/1.80.1/core/str/index.html
doc.rust-lang.org/1.80.1/libc/unix/type.gid_t.html
doc.rust-lang.org/1.80.1/libc/unix/type.pid_t.html
doc.rust-lang.org/1.80.1/libc/unix/type.uid_t.html
doc.rust-lang.org/1.80.1/reference/items/traits.html
doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html
doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html
doc.rust-lang.org/book/ch19-03-advanced-traits.html
doc.rust-lang.org/cargo/reference/build-scripts.html
doc.rust-lang.org/nightly/edition-guide/rust-2024/index.html
doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.MirPhase.html
doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html
doc.rust-lang.org/nomicon/atomics.html
doc.rust-lang.org/nomicon/exotic-sizes.html
doc.rust-lang.org/nomicon/ffi.html
doc.rust-lang.org/nomicon/other-reprs.html
doc.rust-lang.org/nomicon/panic-handler.html
doc.rust-lang.org/reference/attributes/diagnostics.html
doc.rust-lang.org/reference/behavior-considered-undefined.html
doc.rust-lang.org/reference/destructors.html
doc.rust-lang.org/reference/identifiers.html
doc.rust-lang.org/reference/items/modules.html
doc.rust-lang.org/reference/macros-by-example.html
doc.rust-lang.org/reference/names/preludes.html
doc.rust-lang.org/reference/runtime.html
doc.rust-lang.org/reference/subtyping.html
doc.rust-lang.org/reference/type-coercions.html
doc.rust-lang.org/reference/type-layout.html
doc.rust-lang.org/rust-by-example/mod/split.html
doc.rust-lang.org/rustc/platform-support.html
The number of unique, non-source links to doc.rust-lang.org I found across all 5 standard library crates (std, core, alloc, proc_macro, test) is somewhere on the order of over 300. Many of them are duplicated across many different parts of the documentation, for example due to item links in trait implementations.
Contributor guide
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 by reproducing the issue with rustup doc --std while offline, then inspect the generated HTML under /std/ and compare links found by the reported rg command. Separate rustdoc-generated links from explicit links in documentation comments across std, core, alloc, proc_macro, and test; done means the affected local documentation links resolve without relying on doc.rust-lang.org.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, documentation
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100