mirror of
https://github.com/rust-lang/rust.git
synced 2026-05-23 02:27:39 +03:00
Guillaume Gomez
6f222b3f90
feat(rustdoc): stabilize `--emit` flag ### [---> FCP <---](https://github.com/rust-lang/rust/pull/146220#issuecomment-3740447985) ## Stabilization Report: `rustdoc --emit` **Feature:** `rustdoc --emit` **Tracking issue:** rust-lang/rust#83784 **Stabilization PR:** rust-lang/rust#146220 ### What we are stabilizing This stabilizes the `rustdoc --emit` flag, which controls what types of output rustdoc produces. The flag accepts a comma-separated list of the following emit types: - `html-static-files` --- Shared static files with content-hashed filenames for safe caching. - `html-non-static-files` --- Per-crate documentation files with deterministic filenames. - `dep-info[=<path>]` --- A Makefile-compatible `.d` file listing all source files loaded during documentation generation. Same as rustc's dep-info files. When `--emit` is not specified, the default behavior is `--emit=html-static-files,html-non-static-files` (i.e., full HTML documentation output, no dep-info). ### What we are not stabilizing * Interaction between other unstable options, such as `-Zrustdoc-mergeable-info` and `--output-format=doctest` * Available options and the default options when `--emit` not specified. * Extension of per-type emit paths for options currently missing that. ### Motivation #### Cargo The primary consumer is Cargo, which needs `--emit=dep-info=<path>` to precisely track the input dependencies of a rustdoc invocation (see the [`-Zrustdoc-depinfo`] unstable Cargo feature). Without dep-info, Cargo cannot detect changes to files pulled in via `#[path = "..."]` or similar mechanisms and leads to stale documentation in incremental builds. Cargo also uses the selective emission mechanism (`html-static-files` / `html-non-static-files`) when the unstable [`-Zrustdoc-mergeable-info`] feature is active. It skips writing shared static files and search index during per-crate doc generation and defer them to a final merge phase. Under stable usage, Cargo passes all three emit types together. #### docs.rs docs.rs is the other major consumer. It uses selective emission to avoid redundantly copying toolchain-wide static files for every crate, which has historically been a source of breakage. See the tracking rust-lang/rust#83784 and the about page for more <https://docs.rs/about/download>. ### Tests - `tests/run-make/emit-shared-files` --- Verifies selective emission of static vs non-static files. - `tests/run-make/rustdoc-dep-info` --- Verifies dep-info generation, including explicit path and `--out-dir` interaction. - `tests/run-make/rustdoc-scrape-examples-dep-info` --- Verifies dep-info works with scrape-examples. - `tests/run-make/rustdoc-default-output/` --- Verifies `--help` output shows `[html-static-files,html-non-static-files,dep-info]` [`-Zrustdoc-depinfo`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-depinfo [`-Zrustdoc-mergeable-info`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#rustdoc-mergeable-info