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:

rustup/src/toolchain/toolchain.rs

Lines 295 to 304 in ce3c09a

	pub fn doc_path(&self, relative: &str) -> anyhow::Result<PathBuf> {
	let parts = vec!["share", "doc", "rust", "html"];
	let mut doc_dir = self.path.clone();
	for part in parts {
	doc_dir.push(part);
	}
	doc_dir.push(relative);
	Ok(doc_dir)
	}

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

rustup/src/cli/rustup_mode.rs

Lines 1545 to 1563 in b4b9a2e

	const DOCS_DATA: &[(&str, &str, &str)] = &[
	// flags can be used to open specific documents, e.g. `rustup doc --nomicon`
	// tuple elements: document name used as flag, help message, document index path
	("alloc", "The Rust core allocation and collections library", "alloc/index.html"),
	("book", "The Rust Programming Language book", "book/index.html"),
	("cargo", "The Cargo Book", "cargo/index.html"),
	("core", "The Rust Core Library", "core/index.html"),
	("edition-guide", "The Rust Edition Guide", "edition-guide/index.html"),
	("nomicon", "The Dark Arts of Advanced and Unsafe Rust Programming", "nomicon/index.html"),
	("proc_macro", "A support library for macro authors when defining new macros", "proc_macro/index.html"),
	("reference", "The Rust Reference", "reference/index.html"),
	("rust-by-example", "A collection of runnable examples that illustrate various Rust concepts and standard libraries", "rust-by-example/index.html"),
	("rustc", "The compiler for the Rust programming language", "rustc/index.html"),
	("rustdoc", "Documentation generator for Rust projects", "rustdoc/index.html"),
	("std", "Standard library API documentation", "std/index.html"),
	("test", "Support code for rustc's built in unit-test and micro-benchmarking framework", "test/index.html"),
	("unstable-book", "The Unstable Book", "unstable-book/index.html"),
	("embedded-book", "The Embedded Rust Book", "embedded-book/index.html"),
	];

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! ❤️

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 (rust-lang/rust#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"'