Documentation of `rustc` internals

[Ethiraric]

Problem you are trying to solve

I've been trying my hands at solving some clippy issues recently and use rustup doc --std frequently, but I see no option to get the documentation of rustc/nightly-rustc itself. Unless I separately download rustc's source, I can't access the documentation.

What I'm looking for would be the local copy of https://doc.rust-lang.org/stable/nightly-rustc/

I have found nowhere in a --help something that would lead me to that documentation locally.

Solution you'd like

Having a subcommand such as rustup doc --rustc-doc would ideally be the best solution.

Notes

I wouldn't mind tackling this issue if given a bit of guidance and it's not too complex to solve.

[rami3l]

@Ethiraric Thanks a lot for filing this issue!

However, rustup doc is for general-purpose docs like you've probably already seen in rustup doc --help, from the basic tutorials to the unsafe guide, etc.

Since you're developing a particular project (which is clippy), maybe it's better to go with cargo doc for offline docs of clippy and its dependencies (and I suspect those do include Rustc internal crates, otherwise you won't be asking for them), or has that already caused problems for you?

[Ethiraric]

Thank you for your reply!

Unless I am mistaken, cargo doc does not include rustc's internal documentation. I tried both cargo doc and cargo doc --document-private-items, but maybe there is another flag I would need and do not know about? Running cargo doc -p rustc_hir does not match any package.

In the documentation that is generated for clippy items, any reference to one of rustc's internal crates redirects to doc.rust-lang.org.

I understand that rustup doc is for general-purpose docs, but my sentiment is that, since rustc (and its API for access by tools such as clippy) are downloaded by rustup, rustup would be the way for me to access them. If that sentiment is not shared, do feel free to close this issue.

[rami3l]

@Ethiraric I'm sorry to hear that!

On Rustup's side we simply open the prebuilt docs downloaded from the official server with your default browser. The path of the docs relative to your toolchain distribution (by default under ~/.rustup/toolchain/<name>) is calculated as follows:

https://github.com/rust-lang/rustup/blob/ce3c09a0cb126e2c65a3bb2a3bbf3f098b4c23a2/src/toolchain/toolchain.rs#L295-L304

... which just means ./share/doc/rust/html/<something>, where something is one of:

https://github.com/rust-lang/rustup/blob/b4b9a2e7ad260ee2158858632f297e1d2f0aaf26/src/cli/rustup_mode.rs#L1545-L1563

You should be able to find all the docs over there on your disk, actually.

Your feature request is still valid, I think, but it would be a more involved process. We should look at whether to ship these docs offline, and if so, in which distributions (just nightly, I assume?), and how exactly to build them. In short, we also have to inform t-release to make some changes to the main Rust repo.

PS: I've created a new thread on Zulip: https://rust-lang.zulipchat.com/#narrow/stream/241545-t-release/topic/Ship.20Rustc.20internal.20API.20docs.20with.20Rustup.3F

[Ethiraric]

I see. Thanks for all the details! :heart:

If there is something I, as a newcomer to this repository, can act upon, do feel free to reach out to me! I'll fall back to downloading a copy of rustc in the meantime :)

[rbtcollins]

Getting rustc docs into rustup is absolutely doable; the starting point is to get that into the docs packages that we download.

[rami3l]

Getting rustc docs into rustup is absolutely doable; the starting point is to get that into the docs packages that we download.

Oops, looks like it's already there on the server, but Rustup is refusing to install that component (https://github.com/rust-lang/rust/issues/75833)!

info: installing component 'rustc-docs'
info: rolling back changes
error: failed to install component: 'rustc-docs-x86_64-unknown-linux-gnu', detected conflict: '"share/doc/rust/html/rustc"'