Add "--cfg docsrs" to all rustdoc invocations

Author: Urgau

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<String> {
-        vec!["rustdoc".into(), "--lib".into(), "-Zrustdoc-map".into()]
+    fn default_cargo_args(extra_args: &[String]) -> Vec<String> {
+        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,17 +682,15 @@ 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
         let metadata = Metadata {
             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);

templates/core/about/builds.html

@@ -29,6 +29,15 @@ <h4 id="setting-a-readme"> <a href="#setting-a-readme">Setting a README</a> </h4
     </p>
 
     <h4 id="detecting-docsrs"> <a href="#detecting-docsrs">Detecting Docs.rs</a> </h4>
+    <p>
+        To recognize Docs.rs from your Rust code, you can test for the <code>docsrs</code> 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).
+    </p>
     <p>
         To recognize Docs.rs from <code>build.rs</code> files, you can test for the environment variable <code>DOCS_RS</code>, e.g.:
         {% filter highlight(lang="rust") %}{% filter dedent(levels=3) -%}
@@ -48,9 +57,9 @@ <h4 id="cross-compiling"> <a href="#cross-compiling">Cross-compiling</a> </h4>
         You can configure how your crate is built by adding <a href="metadata">package metadata</a> to your <code>Cargo.toml</code>, 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 <code>#[cfg(docsrs)]</code> (not to be confused with <code>#[cfg(doc)]</code>) can be used for conditional compilation.
+        Here, the compiler arguments are set so that <code>#[cfg(my_cfg)]</code> (not to be confused with <code>#[cfg(doc)]</code>) can be used for conditional compilation.
         This approach is also useful for setting <a href="https://doc.rust-lang.org/cargo/reference/features.html">cargo features</a>.
     </p>