Repository: rust
Issue: `rust-docs`/`rustup doc` extremely frequently links to `doc.rust-lang.org` instead of local files, makes offline browsing experience very poor
Labels: T-rustdoc,A-docs,C-bug,T-libs

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:

1. `source` links extremely often do not link to the local files.
    Example: the `source` link of `std::alloc` (module) correctly links to the local files. The `source` link of `std::alloc::alloc` (function) links to `doc.rust-lang.org`.
    Rudimentary grepping for `doc.rust-lang.org` links 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)
2. Some item links such as re-exports link to `doc.rust-lang.org` instead of local files.
    Example: The re-export of `core::arch::*` in `std::arch` links to `doc.rust-lang.org` instead of the local files for `core`.
3. Some relative links in doc comments link to `doc.rust-lang.org` instead of local files.
    Example: In the doc comments for `std::alloc::Global`, the link to `Allocator` (written in-source as ``[`Allocator`]``) correctly links to the local file for the allocator trait, but the link to `free functions in alloc` (written in-source as ``[free functions in `alloc`](self#functions)``) links to `doc.rust-lang.org`.
4. Some documentation *explicitly* links to `doc.rust-lang.org` instead of local files for things like links to the nomicon or the reference.
    Example: Documentation to `std::ffi::c_void` explicitly links to `https://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:

<details>
<summary>
<code>$ rg -oNI 'doc.rust-lang.org/.*?\.html' std/**/*.html | rg -v '/src/' | sort -u</code>
</summary>

```
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
```
</details>

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.