Rustdoc Use Cases: Standard Library, Docs.rs, Local Generation, and Self-Hosted Projects

- For each trait, there is a file under `implementors/.../trait.TraitName.js` containing a list of implementors of that trait. The implementors may be in different crates than the trait, and the JS file is updated as we discover new ones. ## Use cases There are a few major use cases for rustdoc that you should keep in mind when working on it: ### Standard library docs These are published at <https://doc.rust-lang.org/std> as part of the Rust release process. Stable releases are also uploaded to specific versioned URLs like <https://doc.rust-lang.org/1.57.0/std/>. Beta and nightly docs are published to <https://doc.rust-lang.org/beta/std/> and <https://doc.rust-lang.org/nightly/std/>. The docs are uploaded with the [promote-release tool](https://github.com/rust-lang/promote-release) and served from S3 with CloudFront. The standard library docs contain five crates: alloc, core, proc_macro, std, and test. ### docs.rs When crates are published to crates.io, docs.rs automatically builds and publishes their documentation, for instance at <https://docs.rs/serde/latest/serde/>. It always builds with the current nightly rustdoc, so any changes you land in rustdoc are "insta-stable" in that they will have an immediate public effect on docs.rs. Old documentation is not rebuilt, so you will see some variation in UI when browsing old releases in docs.rs. Crate authors can request rebuilds, which will be run with the latest rustdoc. Docs.rs performs some transformations on rustdoc's output in order to save storage and display a navigation bar at the top. In particular, certain static files, like main.js and rustdoc.css, may be shared across multiple invocations of the same version of rustdoc. Others, like crates.js and sidebar-items.js, are different for different invocations. Still others, like fonts, will never change. These categories are distinguished using the `SharedResource` enum in `src/librustdoc/html/render/write_shared.rs` Documentation on docs.rs is always generated for a single crate at a time, so the search and sidebar functionality don't include dependencies of the current crate. ### Locally generated docs Crate authors can run `cargo doc --open` in crates they have checked out locally to see the docs. This is useful to check that the docs they are writing are useful and display correctly. It can also be useful for people to view documentation on crates they aren't authors of, but want to use. In both cases, people may use `--document-private-items` Cargo flag to see private methods, fields, and so on, which are normally not displayed. By default `cargo doc` will generate documentation for a crate and all of its dependencies. That can result in a very large documentation bundle, with a large (and slow) search corpus. The Cargo flag `--no-deps` inhibits that behavior and generates docs for just the crate. ### Self-hosted project docs Some projects like to host their own documentation. For example: <https://docs.serde.rs/>. This is easy to do by locally generating docs, and simply copying them to a web server. Rustdoc's HTML output can be extensively customized by flags. Users can add a theme, set the default theme, and inject arbitrary HTML. See `rustdoc --help` for details.

This section details various use cases for Rustdoc. These include generating standard library documentation published at doc.rust-lang.org, automatically building and publishing crate documentation on docs.rs, locally generating documentation for crate authors to check their documentation, and supporting self-hosted project documentation with customizable HTML output.