Rustdoc's HTML Generation: Leveraging Type Information and Context

[`formats::renderer::run_format`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/formats/renderer/fn.run_format.html [`html/format.rs`]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/format.rs [`html/layout.rs`]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/layout.rs [`html/markdown.rs`]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/markdown.rs [`html/render/mod.rs`]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/render/mod.rs [`html/render/print_item.rs`]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/render/print_item.rs [`librustdoc/formats`]: https://github.com/rust-lang/rust/tree/master/src/librustdoc/formats [`librustdoc/html`]: https://github.com/rust-lang/rust/tree/master/src/librustdoc/html [`print_item`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/html/render/print_item/fn.print_item.html [Askama]: https://docs.rs/askama/latest/askama/ ### From Soup to Nuts (or: ["An Unbroken Thread Stretches From Those First `Cell`s To Us"][video]) [video]: https://www.youtube.com/watch?v=hOLAGYmUQV0 It's important to note that `rustdoc` can ask the compiler for type information directly, even during `HTML` generation. This [didn't used to be the case], and a lot of `rustdoc`'s architecture was designed around not doing that, but a `TyCtxt` is now passed to `formats::renderer::run_format`, which is used to run generation for both `HTML` and the (unstable as of  March 2023) JSON format. This change has allowed other changes to remove data from the "clean" [`AST`][ast] that can be easily derived from `TyCtxt` queries, and we'll usually accept PRs that remove fields from "clean" (it's been soft-deprecated), but this is complicated from two other constraints that `rustdoc` runs under: * Docs can be generated for crates that don't actually pass type checking. This is used for generating docs that cover mutually-exclusive platform configurations, such as `libstd` having a single package of docs that cover all supported operating systems. This means `rustdoc` has to be able to generate docs from `HIR`. * Docs can inline across crates. Since crate metadata doesn't contain `HIR`, it must be possible to generate inlined docs from the `rustc_middle` data. The "clean" [`AST`][ast] acts as a common output format for both input formats. There is also some data in clean that doesn't correspond directly to `HIR`, such as synthetic `impl`s for auto traits and blanket `impl`s generated by the `collect-trait-impls` pass. Some additional data is stored in `html::render::context::{Context, SharedContext}`. These two types serve as ways to segregate `rustdoc`'s data for an eventual future with multithreaded doc generation, as well as just keeping things organized: * [`Context`] stores data used for generating the current page, such as its path, a list of `HTML` IDs that have been used (to avoid duplicate `id=""`), and the pointer to `SharedContext`. * [`SharedContext`] stores data that does not vary by page, such as the `tcx` pointer, and a list of all types. [`Context`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/html/render/context/struct.Context.html [didn't used to be the case]: https://github.com/rust-lang/rust/pull/80090 [`SharedContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/html/render/context/struct.SharedContext.html ## Other Tricks Up Its Sleeve

Rustdoc can now directly access type information from the compiler during HTML generation via the `TyCtxt` passed to `formats::renderer::run_format`. This allows for the removal of redundant data from the "clean" AST, although the process is complicated by the need to generate docs for crates that don't pass type checking and for inlining across crates. The "clean" AST serves as a common output format for both HIR and rustc_middle data. The `html::render::context::{Context, SharedContext}` structs manage data for HTML generation, with `Context` storing page-specific data and `SharedContext` storing data shared across all pages, such as the `tcx` pointer.