rust-lang / rust-lang/rust

`rust-docs`/`rustup doc` extremely frequently links to `doc.rust-lang.org` instead of local files, makes offline browsing experience very poor

Open
#129,148 5 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs C-bug T-libs T-rustdoc
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:

  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:

$ 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

Open the contributing guide

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.