Auto merge of #11503 - willcrichton:scrape-dev-deps-diagnostic, r=weihanglo

Add warning if potentially-scrapable examples are skipped due to dev-dependencies

### What does this PR try to resolve?

Another point of feedback I've received on the scrape-examples feature is that the dev-dependency situation is quite confusing and subtle. To make users more aware of the issue, I added a warning where Cargo will alert users when examples are skipped due to a dev-dependency requirement, along with proposing a fix.

### How should we test and review this PR?

The test `docscrape::no_scrape_with_dev_deps` has been updated to reflect this new warning.

r? `@weihanglo`

(PS thank you for the reviews Weihang. I know I'm doing lots of little patches right now to get this feature finalized. If you want to share the reviewing burden on scrape-examples with anyone else, let me know!)

Author: bors

src/cargo/ops/cargo_compile/unit_generator.rs

@@ -1,3 +1,4 @@
+use std::cell::RefCell;
 use std::collections::{HashMap, HashSet};
 use std::fmt::Write;
 
@@ -458,6 +459,7 @@ impl<'a> UnitGenerator<'a, '_> {
             .map(|u| &u.pkg)
             .collect::<HashSet<_>>();
 
+        let skipped_examples = RefCell::new(Vec::new());
         let can_scrape = |target: &Target| {
             match (target.doc_scrape_examples(), target.is_example()) {
                 // Targets configured by the user to not be scraped should never be scraped
@@ -466,7 +468,14 @@ impl<'a> UnitGenerator<'a, '_> {
                 (RustdocScrapeExamples::Enabled, _) => true,
                 // Example targets with no configuration should be conditionally scraped if
                 // it's guaranteed not to break the build
-                (RustdocScrapeExamples::Unset, true) => safe_to_scrape_example_targets,
+                (RustdocScrapeExamples::Unset, true) => {
+                    if !safe_to_scrape_example_targets {
+                        skipped_examples
+                            .borrow_mut()
+                            .push(target.name().to_string());
+                    }
+                    safe_to_scrape_example_targets
+                }
                 // All other targets are ignored for now. This may change in the future!
                 (RustdocScrapeExamples::Unset, false) => false,
             }
@@ -475,6 +484,18 @@ impl<'a> UnitGenerator<'a, '_> {
         let mut scrape_proposals = self.filter_targets(can_scrape, false, CompileMode::Docscrape);
         scrape_proposals.retain(|proposal| pkgs_to_scrape.contains(proposal.pkg));
 
+        let skipped_examples = skipped_examples.into_inner();
+        if !skipped_examples.is_empty() {
+            let mut shell = self.ws.config().shell();
+            let example_str = skipped_examples.join(", ");
+            shell.warn(format!(
+                "\
+Rustdoc did not scrape the following examples because they require dev-dependencies: {example_str}
+    If you want Rustdoc to scrape these examples, then add `doc-scrape-examples = true`
+    to the [[example]] target configuration of at least one example."
+            ))?;
+        }
+
         Ok(scrape_proposals)
     }
 

tests/testsuite/docscrape.rs

@@ -429,7 +429,7 @@ error: expected one of `!` or `::`, found `NOT`
 fn no_scrape_with_dev_deps() {
     // Tests that a crate with dev-dependencies does not have its examples
     // scraped unless explicitly prompted to check them. See
-    // `CompileFilter::refine_for_docscrape` for details on why.
+    // `UnitGenerator::create_docscrape_proposals` for details on why.
 
     let p = project()
         .file(
@@ -440,9 +440,6 @@ fn no_scrape_with_dev_deps() {
             version = "0.0.1"
             authors = []
 
-            [lib]
-            doc-scrape-examples = false
-
             [dev-dependencies]
             a = {path = "a"}
         "#,
@@ -461,17 +458,21 @@ fn no_scrape_with_dev_deps() {
         .file("a/src/lib.rs", "pub fn f() {}")
         .build();
 
-    // If --examples is not provided, then the example is never scanned.
+    // If --examples is not provided, then the example is not scanned, and a warning
+    // should be raised.
     p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples")
         .masquerade_as_nightly_cargo(&["rustdoc-scrape-examples"])
         .with_stderr(
             "\
+warning: Rustdoc did not scrape the following examples because they require dev-dependencies: ex
+    If you want Rustdoc to scrape these examples, then add `doc-scrape-examples = true`
+    to the [[example]] target configuration of at least one example.
 [DOCUMENTING] foo v0.0.1 ([CWD])
 [FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
         )
         .run();
 
-    // If --examples is provided, then the bad example is scanned and ignored.
+    // If --examples is provided, then the example is scanned.
     p.cargo("doc --examples -Zunstable-options -Z rustdoc-scrape-examples")
         .masquerade_as_nightly_cargo(&["rustdoc-scrape-examples"])
         .with_stderr_unordered(
@@ -497,9 +498,6 @@ fn use_dev_deps_if_explicitly_enabled() {
             version = "0.0.1"
             authors = []
 
-            [lib]
-            doc-scrape-examples = false
-
             [[example]]
             name = "ex"
             doc-scrape-examples = true