Rollup merge of #146220 - weihanglo:rustdoc-emit, r=GuillaumeGomez

feat(rustdoc): stabilize `--emit` flag

### [---> FCP <---](#146220 (comment))

## Stabilization Report: `rustdoc --emit`

**Feature:** `rustdoc --emit`
**Tracking issue:** #83784
**Stabilization PR:** #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 #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

Author: GuillaumeGomez

src/doc/rustdoc/src/command-line-arguments.md

@@ -440,6 +440,37 @@ When `rustdoc` receives this flag, it will print an extra "Version (version)" in
 the crate root's docs. You can use this flag to differentiate between different versions of your
 library's documentation.
 
+## `--emit`: control the types of output for rustdoc to emit
+
+This flag controls the types of output by rustdoc. It accepts a comma-separated
+list of values, and may be specified multiple times. The valid emit kinds are:
+
+- `html-static-files` --- Generates shared static files whose contents are
+  tied to a specific toolchain version. These are written with a filename
+  that includes a hash of their contents, so they are safe to cache with
+  the change if the toolchain version or their contents change, or with the
+  `Cache-Control: immutable` directive.
+- `html-non-static-files` --- Generates files based on the crate(s) being
+  documented. These file names need to be deterministic so there is no
+  content-hash in their file names.
+- `dep-info` --- Generates a file with Makefile syntax that indicates all the
+  source files that were loaded to document the crate. The default output
+  filename is `CRATE_NAME.d`. This emit type can can optionally be followed by
+  `=` to specify an explicit output path, for example,
+  `--emit=dep-info=/path/to/foo.d`. The output can be sent to stdout by
+  specifying `-` as the path (e.g., `--emit=dep-info=-`).
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --emit=html-static-files,html-non-static-files,dep-info=/path/to/build/cache/foo.d
+```
+
+If not specified, the default emit types would be
+`--emit=html-static-files,html-non-static-files`.
+
+Output files are written to the current directory unless the `--out-dir` flag is used.
+
 ## `-`: load source code from the standard input
 
 If you specify `-` as the INPUT on the command line, then `rustdoc` will read the

src/librustdoc/lib.rs

@@ -534,7 +534,7 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
         ),
         opt(
-            Unstable,
+            Stable,
             Multi,
             "",
             "emit",