From 6b9a28eb21594cb4fdfafc92c763360a689a0c50 Mon Sep 17 00:00:00 2001 From: Will Crichton Date: Tue, 20 Dec 2022 12:54:48 -0800 Subject: [PATCH 1/2] Add warning if potentially-scrapable examples are skipped due to dev-dependencies --- src/cargo/ops/cargo_compile/unit_generator.rs | 25 ++++++++++++++++++- tests/testsuite/docscrape.rs | 16 ++++++------ 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/src/cargo/ops/cargo_compile/unit_generator.rs b/src/cargo/ops/cargo_compile/unit_generator.rs index 53012dcd03c..e1ed29d49d3 100644 --- a/src/cargo/ops/cargo_compile/unit_generator.rs +++ b/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::>(); + let skipped_examples: RefCell> = 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,12 @@ 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.clone()); + } + safe_to_scrape_example_targets + } // All other targets are ignored for now. This may change in the future! (RustdocScrapeExamples::Unset, false) => false, } @@ -475,6 +482,22 @@ 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 + .into_iter() + .map(|t| t.description_named()) + .collect::>() + .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) } diff --git a/tests/testsuite/docscrape.rs b/tests/testsuite/docscrape.rs index f9f0d0a601f..76c04147f25 100644 --- a/tests/testsuite/docscrape.rs +++ b/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: example \"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 From 1c4065c52e6a2b81186a4a8b8a6b9e2134f10357 Mon Sep 17 00:00:00 2001 From: Will Crichton Date: Thu, 22 Dec 2022 12:37:11 -0800 Subject: [PATCH 2/2] Simplify code and output of skipped_examples warning --- src/cargo/ops/cargo_compile/unit_generator.rs | 12 +++++------- tests/testsuite/docscrape.rs | 2 +- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/src/cargo/ops/cargo_compile/unit_generator.rs b/src/cargo/ops/cargo_compile/unit_generator.rs index e1ed29d49d3..1a83be55424 100644 --- a/src/cargo/ops/cargo_compile/unit_generator.rs +++ b/src/cargo/ops/cargo_compile/unit_generator.rs @@ -459,7 +459,7 @@ impl<'a> UnitGenerator<'a, '_> { .map(|u| &u.pkg) .collect::>(); - let skipped_examples: RefCell> = RefCell::new(Vec::new()); + 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 @@ -470,7 +470,9 @@ impl<'a> UnitGenerator<'a, '_> { // it's guaranteed not to break the build (RustdocScrapeExamples::Unset, true) => { if !safe_to_scrape_example_targets { - skipped_examples.borrow_mut().push(target.clone()); + skipped_examples + .borrow_mut() + .push(target.name().to_string()); } safe_to_scrape_example_targets } @@ -485,11 +487,7 @@ impl<'a> UnitGenerator<'a, '_> { let skipped_examples = skipped_examples.into_inner(); if !skipped_examples.is_empty() { let mut shell = self.ws.config().shell(); - let example_str = skipped_examples - .into_iter() - .map(|t| t.description_named()) - .collect::>() - .join(", "); + let example_str = skipped_examples.join(", "); shell.warn(format!( "\ Rustdoc did not scrape the following examples because they require dev-dependencies: {example_str} diff --git a/tests/testsuite/docscrape.rs b/tests/testsuite/docscrape.rs index 76c04147f25..6a20540e1fb 100644 --- a/tests/testsuite/docscrape.rs +++ b/tests/testsuite/docscrape.rs @@ -464,7 +464,7 @@ fn no_scrape_with_dev_deps() { .masquerade_as_nightly_cargo(&["rustdoc-scrape-examples"]) .with_stderr( "\ -warning: Rustdoc did not scrape the following examples because they require dev-dependencies: example \"ex\" +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])