development/cargo
development/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo synced 2024-09-18 07:12:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse source
This commit is contained in:
Will Crichton 2022-12-20 12:54:48 -08:00
parent eb829cfb35
commit 6b9a28eb21
2 changed files with 31 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
src/cargo/ops/cargo_compile/unit_generator.rs
View file

@ -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<Vec<Target>> = 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::<Vec<_>>()
.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)
}

16
tests/testsuite/docscrape.rs
View file

@ -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