From 240d3e84be939d0bcf9ed797ec1fbcfb00c686d1 Mon Sep 17 00:00:00 2001 From: Urgau Date: Tue, 23 Jan 2024 10:29:42 +0100 Subject: [PATCH] Add "--cfg docsrs" to all rustdoc invocations --- crates/metadata/lib.rs | 42 +++++++++++++++++++++++--------- templates/core/about/builds.html | 13 ++++++++-- 2 files changed, 41 insertions(+), 14 deletions(-) diff --git a/crates/metadata/lib.rs b/crates/metadata/lib.rs index b076494a5..1ed282e85 100644 --- a/crates/metadata/lib.rs +++ b/crates/metadata/lib.rs @@ -267,7 +267,12 @@ impl Metadata { cargo_args.push("--no-default-features".into()); } - let mut all_rustdoc_args = self.rustdoc_args.clone(); + // Unconditionnaly set `--cfg docsrs` as it has become a de-facto way to + // distinguish docs.rs. + // + // See https://github.com/rust-lang/docs.rs/issues/2389. + let mut all_rustdoc_args = vec!["--cfg".into(), "docsrs".into()]; + all_rustdoc_args.extend_from_slice(&self.rustdoc_args); all_rustdoc_args.extend_from_slice(rustdoc_args); // Pass `RUSTFLAGS` and `RUSTDOCFLAGS` using `cargo --config`, which handles whitespace correctly. @@ -650,14 +655,20 @@ mod test_targets { mod test_calculations { use super::*; - fn default_cargo_args() -> Vec { - vec!["rustdoc".into(), "--lib".into(), "-Zrustdoc-map".into()] + fn default_cargo_args(extra_args: &[String]) -> Vec { + let mut args = vec!["rustdoc".into(), "--lib".into(), "-Zrustdoc-map".into()]; + args.extend_from_slice(extra_args); + args.extend_from_slice(&[ + "--config".into(), + r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(), + ]); + args } #[test] fn test_defaults() { let metadata = Metadata::default(); - assert_eq!(metadata.cargo_args(&[], &[]), default_cargo_args()); + assert_eq!(metadata.cargo_args(&[], &[]), default_cargo_args(&[])); let env = metadata.environment_variables(); assert_eq!(env.get("DOCS_RS").map(String::as_str), Some("1")); assert!(env.get("RUSTDOCFLAGS").is_none()); @@ -671,8 +682,7 @@ mod test_calculations { all_features: true, ..Metadata::default() }; - let mut expected_args = default_cargo_args(); - expected_args.push("--all-features".into()); + let expected_args = default_cargo_args(&["--all-features".into()]); assert_eq!(metadata.cargo_args(&[], &[]), expected_args); // no default features @@ -680,8 +690,7 @@ mod test_calculations { no_default_features: true, ..Metadata::default() }; - let mut expected_args = default_cargo_args(); - expected_args.push("--no-default-features".into()); + let expected_args = default_cargo_args(&["--no-default-features".into()]); assert_eq!(metadata.cargo_args(&[], &[]), expected_args); // allow passing both even though it's nonsense; cargo will give an error anyway @@ -690,9 +699,8 @@ mod test_calculations { no_default_features: true, ..Metadata::default() }; - let mut expected_args = default_cargo_args(); - expected_args.push("--all-features".into()); - expected_args.push("--no-default-features".into()); + let expected_args = + default_cargo_args(&["--all-features".into(), "--no-default-features".into()]); assert_eq!(metadata.cargo_args(&[], &[]), expected_args); // explicit empty vec @@ -706,6 +714,8 @@ mod test_calculations { "-Zrustdoc-map".into(), "--features".into(), String::new(), + "--config".into(), + r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); @@ -720,6 +730,8 @@ mod test_calculations { "-Zrustdoc-map".into(), "--features".into(), "some_feature".into(), + "--config".into(), + r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); @@ -734,6 +746,8 @@ mod test_calculations { "-Zrustdoc-map".into(), "--features".into(), "feature1 feature2".into(), + "--config".into(), + r#"build.rustdocflags=["--cfg", "docsrs"]"#.into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); @@ -754,7 +768,7 @@ mod test_calculations { "--lib".into(), "-Zrustdoc-map".into(), "--config".into(), - r#"build.rustdocflags=["-Z", "unstable-options", "--static-root-path", "/", "--cap-lints", "warn"]"#.into(), + r#"build.rustdocflags=["--cfg", "docsrs", "-Z", "unstable-options", "--static-root-path", "/", "--cap-lints", "warn"]"#.into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); @@ -773,6 +787,8 @@ mod test_calculations { "-Ztarget-applies-to-host".into(), "--config".into(), "host.rustflags=[\"--cfg\", \"x\"]".into(), + "--config".into(), + "build.rustdocflags=[\"--cfg\", \"docsrs\"]".into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); @@ -785,6 +801,8 @@ mod test_calculations { String::from("rustdoc"), "--lib".into(), "-Zrustdoc-map".into(), + "--config".into(), + "build.rustdocflags=[\"--cfg\", \"docsrs\"]".into(), "-Zbuild-std".into(), ]; assert_eq!(metadata.cargo_args(&[], &[]), expected_args); diff --git a/templates/core/about/builds.html b/templates/core/about/builds.html index 93a47f7f3..4c6c6a50a 100644 --- a/templates/core/about/builds.html +++ b/templates/core/about/builds.html @@ -29,6 +29,15 @@

Setting a README

Detecting Docs.rs

+

+ To recognize Docs.rs from your Rust code, you can test for the docsrs cfg, e.g.: + {% filter highlight(lang="rust") %}{% filter dedent(levels=3) -%} + #[cfg(docsrs)] + mod documentation; + {%- endfilter %}{% endfilter %} + The `docsrs` cfg only applies to the final rustdoc invocation (i.e. the crate currently + being documented). It does not apply to dependencies (including workspace ones). +

To recognize Docs.rs from build.rs files, you can test for the environment variable DOCS_RS, e.g.: {% filter highlight(lang="rust") %}{% filter dedent(levels=3) -%} @@ -48,9 +57,9 @@

Cross-compiling

You can configure how your crate is built by adding package metadata to your Cargo.toml, e.g.: {% filter highlight(lang="toml") %}{% filter dedent -%} [package.metadata.docs.rs] - rustc-args = ["--cfg", "docsrs"] + rustc-args = ["--cfg", "my_cfg"] {%- endfilter %}{% endfilter %} - Here, the compiler arguments are set so that #[cfg(docsrs)] (not to be confused with #[cfg(doc)]) can be used for conditional compilation. + Here, the compiler arguments are set so that #[cfg(my_cfg)] (not to be confused with #[cfg(doc)]) can be used for conditional compilation. This approach is also useful for setting cargo features.