From c6b7f630a5365ccfe2d4f24c7f5a4cc8499c5a55 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Thu, 5 Mar 2026 12:25:24 -0700 Subject: [PATCH] rustdoc: rename `--emit` names These new names are pithier and match up with the rest of our terminology: - `--emit=html-static-files` matches the default name of the directory that it actually emits, which is `static.files` (the hyphen is used for emit because every other emit option uses hyphens, but the directory uses a dot because we don't want its name to conflict with a crate). - `--emit=html-non-static-files` matches the convention that emit is a noun, not an adjective. It also matches up with static-files, and it logically groups with other data formats. This commit changes the docs, but leaves in support for the old names, to break the cycle with cargo and docs.rs. This commit needs merged, then cargo and docs.rs will be updated to use the new names, then, finally, the old names will be removed. --- src/librustdoc/config.rs | 14 +++++++++----- src/librustdoc/html/render/write_shared.rs | 2 +- src/librustdoc/lib.rs | 2 +- tests/run-make/emit-shared-files/rmake.rs | 4 ++-- .../rustdoc-default-output/output-default.stdout | 2 +- 5 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 3d4b4e969157c..f1fdce48181c2 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -322,8 +322,8 @@ pub(crate) enum ModuleSorting { #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) enum EmitType { - Toolchain, - InvocationSpecific, + HtmlStaticFiles, + HtmlNonStaticFiles, DepInfo(Option), } @@ -332,8 +332,12 @@ impl FromStr for EmitType { fn from_str(s: &str) -> Result { match s { - "toolchain-shared-resources" => Ok(Self::Toolchain), - "invocation-specific" => Ok(Self::InvocationSpecific), + // old nightly-only choices that are going away soon + "toolchain-shared-resources" => Ok(Self::HtmlStaticFiles), + "invocation-specific" => Ok(Self::HtmlNonStaticFiles), + // modern choices + "html-static-files" => Ok(Self::HtmlStaticFiles), + "html-non-static-files" => Ok(Self::HtmlNonStaticFiles), "dep-info" => Ok(Self::DepInfo(None)), option => match option.strip_prefix("dep-info=") { Some("-") => Ok(Self::DepInfo(Some(OutFileName::Stdout))), @@ -346,7 +350,7 @@ impl FromStr for EmitType { impl RenderOptions { pub(crate) fn should_emit_crate(&self) -> bool { - self.emit.is_empty() || self.emit.contains(&EmitType::InvocationSpecific) + self.emit.is_empty() || self.emit.contains(&EmitType::HtmlNonStaticFiles) } pub(crate) fn dep_info(&self) -> Option> { diff --git a/src/librustdoc/html/render/write_shared.rs b/src/librustdoc/html/render/write_shared.rs index 1b5dbeed8de80..b1c77063ca94e 100644 --- a/src/librustdoc/html/render/write_shared.rs +++ b/src/librustdoc/html/render/write_shared.rs @@ -218,7 +218,7 @@ fn write_static_files( try_err!(fs::write(&dst_path, buffer), &dst_path); } - if opt.emit.is_empty() || opt.emit.contains(&EmitType::Toolchain) { + if opt.emit.is_empty() || opt.emit.contains(&EmitType::HtmlStaticFiles) { static_files::for_each(|f: &static_files::StaticFile| { let filename = static_dir.join(f.output_filename()); let contents: &[u8] = diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 8cad0210ea346..3445221e4dcee 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -537,7 +537,7 @@ fn opts() -> Vec { "", "emit", "Comma separated list of types of output for rustdoc to emit", - "[toolchain-shared-resources,invocation-specific,dep-info]", + "[html-static-files,html-non-static-files,dep-info]", ), opt(Unstable, FlagMulti, "", "no-run", "Compile doctests without running them", ""), opt( diff --git a/tests/run-make/emit-shared-files/rmake.rs b/tests/run-make/emit-shared-files/rmake.rs index bd868d4fd19e2..9841dce27fa2f 100644 --- a/tests/run-make/emit-shared-files/rmake.rs +++ b/tests/run-make/emit-shared-files/rmake.rs @@ -34,7 +34,7 @@ fn main() { rustdoc() .arg("-Zunstable-options") - .arg("--emit=toolchain-shared-resources") + .arg("--emit=html-static-files") .out_dir("toolchain-only") .arg("--resource-suffix=-xxx") .args(&["--extend-css", "z.css"]) @@ -68,7 +68,7 @@ fn main() { rustdoc() .arg("-Zunstable-options") - .arg("--emit=toolchain-shared-resources") + .arg("--emit=html-static-files") .out_dir("all-shared") .arg("--resource-suffix=-xxx") .args(&["--extend-css", "z.css"]) diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout index 4e28be347cbb1..bc3a67a1ebcdc 100644 --- a/tests/run-make/rustdoc-default-output/output-default.stdout +++ b/tests/run-make/rustdoc-default-output/output-default.stdout @@ -150,7 +150,7 @@ Options: --generate-redirect-map Generate JSON file at the top level instead of generating HTML redirection files - --emit [toolchain-shared-resources,invocation-specific,dep-info] + --emit [html-static-files,html-non-static-files,dep-info] Comma separated list of types of output for rustdoc to emit --no-run Compile doctests without running them