rust-lang/rust

rustdoc

rustdoc is the official documentation generator for Rust crates. It ships with every rustup installation and is what's behind cargo doc.

Where it lives

The implementation is split between two paths:

src/librustdoc/ — the rustdoc library. Contains the entire engine: clean pass, doctest extraction, HTML rendering, JSON rendering, search index generation.
src/tools/rustdoc/ — a thin shim crate whose main.rs calls into librustdoc. The shim exists so that the binary can be a separate Cargo target without librustdoc having to be a binary itself.

Output formats are also separately exposed:

HTML is the default (what people read on docs.rs)
JSON is exposed for IDE/tooling consumers — schema lives in src/rustdoc-json-types/

How rustdoc works

graph LR
    Src["my_crate.rs"] --> EmbedRustc["Embedded rustc<br/>(via rustc_driver Callbacks)"]
    EmbedRustc --> Hir[(HIR + types)]
    Hir --> Clean["clean::<br/>HIR → rustdoc IR"]
    Clean --> Cleaned[("rustdoc::clean::Item tree")]
    Cleaned --> Render
    Render -.HTML.-> Html["target/doc/.../*.html"]
    Render -.JSON.-> JSON["target/doc/foo.json"]
    Cleaned --> Doctest["doctest extraction"]
    Doctest --> RunCompile["compile + run examples"]

Rustdoc embeds rustc through rustc_driver::Callbacks — same compiler, same parsing, same type checking. After analysis it intercepts the HIR and walks it, building a "cleaned" tree (librustdoc::clean::*) that's documentation-friendly: items have docstrings attached, generics are pretty-printable, traits are linked.

The cleaned tree is then passed to a renderer:

HTML renderer (librustdoc::html::*) — produces the familiar target/doc/ directory with index.html, crate-name/, static/ (CSS, JS, search index)
JSON renderer (librustdoc::json::*) — produces a single crate-name.json file conforming to src/rustdoc-json-types/

Doctests

The doctest pipeline is one of rustdoc's bigger features:

Walk the cleaned tree, find code blocks marked as Rust (default for rust and rs info-strings)
Extract each block, possibly rewriting it (auto-fn main(), hide markers #)
Compile each one with rustc (with the right edition, features, target)
Optionally run it (cargo test --doc)

This is implemented in librustdoc::doctest. Doctests caught a lot of regressions historically because they exercise the public API in a way unit tests in the same crate don't.

Search

The HTML output includes a JS search box that hits an index loaded from search-index.js. The index is a compact serialization of all items, their types, and short descriptions, generated by librustdoc::html::render::search_index. The search itself is in static/search.js.

Themes and CSS

rustdoc ships several themes (light, dark, ayu, system). The CSS lives under src/librustdoc/html/static/css/. Theme correctness is enforced by tests in tests/rustdoc-html/ and visual tests in tests/rustdoc-gui/ (driven by src/tools/rustdoc-gui-test/, which runs Chromium via browser-ui-test).

JSON output

The unstable JSON output is consumed by a small but important set of tools — most notably the docs.rs search index and IDE integrations. Schema is in src/rustdoc-json-types/, and changes are validated by src/tools/jsondocck/ and src/tools/jsondoclint/.

When the schema changes the version is bumped; consumers pin to a major version.

Tests

Suite	Purpose
`tests/rustdoc-html/`	Validate generated HTML against `@has` / `@matches` patterns
`tests/rustdoc-json/`	Validate JSON output
`tests/rustdoc-ui/`	rustdoc diagnostics (UI-test-style)
`tests/rustdoc-gui/`	Visual / interactive HTML tests
`tests/rustdoc-js/`	Search behavior tests
`tests/rustdoc-js-std/`	Search behavior against `std`

Doctests for std

./x test core/alloc/std --doc runs the doctests in the standard library. There are thousands — the std API surface is heavily exemplified.

Entry points for modification

New CLI flag → librustdoc::config
New rendering feature → librustdoc::html::render
New JSON field → src/rustdoc-json-types/ (bump version) + the matching librustdoc::json change
A doctest behavior change → librustdoc::doctest
HTML/CSS/JS changes → src/librustdoc/html/static/, validated by tests/rustdoc-html/ and tests/rustdoc-gui/