mirror of
https://github.com/rust-lang/cargo
synced 2024-08-24 18:15:45 +00:00
Auto merge of #10017 - willcrichton:example-analyzer, r=alexcrichton
Change --scrape-examples flag to -Z rustdoc-scrape-examples I'm working on getting the scrape examples feature working on docs.rs. However, docs.rs uses `cargo rustdoc` instead of `cargo doc`, and right now the `--scrape-examples` flag is only allowed for `cargo doc`. So this PR changes it to a `-Z` flag that can be passed to either command.
This commit is contained in:
commit
4cc3f4f193
|
@ -1,7 +1,6 @@
|
|||
use crate::command_prelude::*;
|
||||
|
||||
use anyhow::anyhow;
|
||||
use cargo::ops::{self, CompileFilter, DocOptions, FilterRule, LibRule};
|
||||
use cargo::ops::{self, DocOptions};
|
||||
|
||||
pub fn cli() -> App {
|
||||
subcommand("doc")
|
||||
|
@ -20,13 +19,6 @@ pub fn cli() -> App {
|
|||
)
|
||||
.arg(opt("no-deps", "Don't build documentation for dependencies"))
|
||||
.arg(opt("document-private-items", "Document private items"))
|
||||
.arg(
|
||||
opt(
|
||||
"scrape-examples",
|
||||
"Scrape examples to include as function documentation",
|
||||
)
|
||||
.value_name("FLAGS"),
|
||||
)
|
||||
.arg_jobs()
|
||||
.arg_targets_lib_bin_example(
|
||||
"Document only this package's library",
|
||||
|
@ -56,33 +48,6 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
|
|||
args.compile_options(config, mode, Some(&ws), ProfileChecking::Custom)?;
|
||||
compile_opts.rustdoc_document_private_items = args.is_present("document-private-items");
|
||||
|
||||
// TODO(wcrichto): move scrape example configuration into Cargo.toml before stabilization
|
||||
// See: https://github.com/rust-lang/cargo/pull/9525#discussion_r728470927
|
||||
compile_opts.rustdoc_scrape_examples = match args.value_of("scrape-examples") {
|
||||
Some(s) => Some(match s {
|
||||
"all" => CompileFilter::new_all_targets(),
|
||||
"examples" => CompileFilter::new(
|
||||
LibRule::False,
|
||||
FilterRule::none(),
|
||||
FilterRule::none(),
|
||||
FilterRule::All,
|
||||
FilterRule::none(),
|
||||
),
|
||||
_ => {
|
||||
return Err(CliError::from(anyhow!(
|
||||
r#"--scrape-examples must take "all" or "examples" as an argument"#
|
||||
)));
|
||||
}
|
||||
}),
|
||||
None => None,
|
||||
};
|
||||
|
||||
if compile_opts.rustdoc_scrape_examples.is_some() {
|
||||
config
|
||||
.cli_unstable()
|
||||
.fail_if_stable_opt("--scrape-examples", 9910)?;
|
||||
}
|
||||
|
||||
let doc_opts = DocOptions {
|
||||
open_result: args.is_present("open"),
|
||||
compile_opts,
|
||||
|
|
|
@ -654,6 +654,9 @@ unstable_cli_options!(
|
|||
timings: Option<Vec<String>> = ("Display concurrency information"),
|
||||
unstable_options: bool = ("Allow the usage of unstable options"),
|
||||
weak_dep_features: bool = ("Allow `dep_name?/feature` feature syntax"),
|
||||
// TODO(wcrichto): move scrape example configuration into Cargo.toml before stabilization
|
||||
// See: https://github.com/rust-lang/cargo/pull/9525#discussion_r728470927
|
||||
rustdoc_scrape_examples: Option<String> = ("Allow rustdoc to scrape examples from reverse-dependencies for documentation"),
|
||||
skip_rustdoc_fingerprint: bool = (HIDDEN),
|
||||
);
|
||||
|
||||
|
@ -871,6 +874,7 @@ impl CliUnstable {
|
|||
"namespaced-features" => self.namespaced_features = parse_empty(k, v)?,
|
||||
"weak-dep-features" => self.weak_dep_features = parse_empty(k, v)?,
|
||||
"credential-process" => self.credential_process = parse_empty(k, v)?,
|
||||
"rustdoc-scrape-examples" => self.rustdoc_scrape_examples = v.map(|s| s.to_string()),
|
||||
"skip-rustdoc-fingerprint" => self.skip_rustdoc_fingerprint = parse_empty(k, v)?,
|
||||
"compile-progress" => stabilized_warn(k, "1.30", STABILIZED_COMPILE_PROGRESS),
|
||||
"offline" => stabilized_err(k, "1.36", STABILIZED_OFFLINE)?,
|
||||
|
|
|
@ -45,7 +45,7 @@ use crate::util::interning::InternedString;
|
|||
use crate::util::restricted_names::is_glob_pattern;
|
||||
use crate::util::{closest_msg, profile, CargoResult, StableHasher};
|
||||
|
||||
use anyhow::Context as _;
|
||||
use anyhow::{bail, Context as _};
|
||||
|
||||
/// Contains information about how a package should be compiled.
|
||||
///
|
||||
|
@ -76,9 +76,6 @@ pub struct CompileOptions {
|
|||
/// Whether the `--document-private-items` flags was specified and should
|
||||
/// be forwarded to `rustdoc`.
|
||||
pub rustdoc_document_private_items: bool,
|
||||
/// Whether the `--scrape-examples` flag was specified and build flags for
|
||||
/// examples should be forwarded to `rustdoc`.
|
||||
pub rustdoc_scrape_examples: Option<CompileFilter>,
|
||||
/// Whether the build process should check the minimum Rust version
|
||||
/// defined in the cargo metadata for a crate.
|
||||
pub honor_rust_version: bool,
|
||||
|
@ -97,7 +94,6 @@ impl<'a> CompileOptions {
|
|||
target_rustc_args: None,
|
||||
local_rustdoc_args: None,
|
||||
rustdoc_document_private_items: false,
|
||||
rustdoc_scrape_examples: None,
|
||||
honor_rust_version: true,
|
||||
})
|
||||
}
|
||||
|
@ -338,7 +334,6 @@ pub fn create_bcx<'a, 'cfg>(
|
|||
ref target_rustc_args,
|
||||
ref local_rustdoc_args,
|
||||
rustdoc_document_private_items,
|
||||
ref rustdoc_scrape_examples,
|
||||
honor_rust_version,
|
||||
} = *options;
|
||||
let config = ws.config();
|
||||
|
@ -369,6 +364,7 @@ pub fn create_bcx<'a, 'cfg>(
|
|||
let target_data = RustcTargetData::new(ws, &build_config.requested_kinds)?;
|
||||
|
||||
let all_packages = &Packages::All;
|
||||
let rustdoc_scrape_examples = &config.cli_unstable().rustdoc_scrape_examples;
|
||||
let need_reverse_dependencies = rustdoc_scrape_examples.is_some();
|
||||
let full_specs = if need_reverse_dependencies {
|
||||
all_packages
|
||||
|
@ -506,7 +502,22 @@ pub fn create_bcx<'a, 'cfg>(
|
|||
)?;
|
||||
|
||||
let mut scrape_units = match rustdoc_scrape_examples {
|
||||
Some(scrape_filter) => {
|
||||
Some(arg) => {
|
||||
let filter = match arg.as_str() {
|
||||
"all" => CompileFilter::new_all_targets(),
|
||||
"examples" => CompileFilter::new(
|
||||
LibRule::False,
|
||||
FilterRule::none(),
|
||||
FilterRule::none(),
|
||||
FilterRule::All,
|
||||
FilterRule::none(),
|
||||
),
|
||||
_ => {
|
||||
bail!(
|
||||
r#"-Z rustdoc-scrape-examples must take "all" or "examples" as an argument"#
|
||||
)
|
||||
}
|
||||
};
|
||||
let to_build_ids = resolve.specs_to_ids(&resolve_specs)?;
|
||||
let to_builds = pkg_set.get_many(to_build_ids)?;
|
||||
let mode = CompileMode::Docscrape;
|
||||
|
@ -514,7 +525,7 @@ pub fn create_bcx<'a, 'cfg>(
|
|||
generate_targets(
|
||||
ws,
|
||||
&to_builds,
|
||||
scrape_filter,
|
||||
&filter,
|
||||
&build_config.requested_kinds,
|
||||
explicit_host_kind,
|
||||
mode,
|
||||
|
|
|
@ -765,7 +765,6 @@ fn run_verify(
|
|||
target_rustc_args: rustc_args,
|
||||
local_rustdoc_args: None,
|
||||
rustdoc_document_private_items: false,
|
||||
rustdoc_scrape_examples: None,
|
||||
honor_rust_version: true,
|
||||
},
|
||||
&exec,
|
||||
|
|
|
@ -544,7 +544,6 @@ pub trait ArgMatchesExt {
|
|||
target_rustc_args: None,
|
||||
local_rustdoc_args: None,
|
||||
rustdoc_document_private_items: false,
|
||||
rustdoc_scrape_examples: None,
|
||||
honor_rust_version: !self._is_present("ignore-rust-version"),
|
||||
};
|
||||
|
||||
|
|
|
@ -1390,11 +1390,11 @@ Custom named profiles have been stabilized in the 1.57 release. See the
|
|||
* RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123)
|
||||
* Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)
|
||||
|
||||
The `--scrape-examples` argument to the `doc` command tells Rustdoc to search
|
||||
crates in the current workspace for calls to functions. Those call-sites are then
|
||||
included as documentation. The flag can take an argument of `all` or `examples`
|
||||
which configures which crate in the workspace to analyze for examples. For instance:
|
||||
The `-Z rustdoc-scrape-examples` argument tells Rustdoc to search crates in the current workspace
|
||||
for calls to functions. Those call-sites are then included as documentation. The flag can take an
|
||||
argument of `all` or `examples` which configures which crate in the workspace to analyze for examples.
|
||||
For instance:
|
||||
|
||||
```
|
||||
cargo doc -Z unstable-options --scrape-examples examples
|
||||
cargo doc -Z unstable-options -Z rustdoc-scrape-examples=examples
|
||||
```
|
||||
|
|
|
@ -2152,7 +2152,7 @@ fn doc_fingerprint_unusual_behavior() {
|
|||
#[cargo_test]
|
||||
fn scrape_examples_basic() {
|
||||
if !is_nightly() {
|
||||
// --scrape-examples is unstable
|
||||
// -Z rustdoc-scrape-examples is unstable
|
||||
return;
|
||||
}
|
||||
|
||||
|
@ -2170,7 +2170,7 @@ fn scrape_examples_basic() {
|
|||
.file("src/lib.rs", "pub fn foo() {}\npub fn bar() { foo(); }")
|
||||
.build();
|
||||
|
||||
p.cargo("doc -Zunstable-options --scrape-examples all")
|
||||
p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
|
||||
.masquerade_as_nightly_cargo()
|
||||
.with_stderr(
|
||||
"\
|
||||
|
@ -2192,7 +2192,7 @@ fn scrape_examples_basic() {
|
|||
#[cargo_test]
|
||||
fn scrape_examples_avoid_build_script_cycle() {
|
||||
if !is_nightly() {
|
||||
// --scrape-examples is unstable
|
||||
// -Z rustdoc-scrape-examples is unstable
|
||||
return;
|
||||
}
|
||||
|
||||
|
@ -2231,7 +2231,7 @@ fn scrape_examples_avoid_build_script_cycle() {
|
|||
.file("bar/build.rs", "fn main(){}")
|
||||
.build();
|
||||
|
||||
p.cargo("doc --all -Zunstable-options --scrape-examples all")
|
||||
p.cargo("doc --all -Zunstable-options -Z rustdoc-scrape-examples=all")
|
||||
.masquerade_as_nightly_cargo()
|
||||
.run();
|
||||
}
|
||||
|
@ -2239,7 +2239,7 @@ fn scrape_examples_avoid_build_script_cycle() {
|
|||
#[cargo_test]
|
||||
fn scrape_examples_complex_reverse_dependencies() {
|
||||
if !is_nightly() {
|
||||
// --scrape-examples is unstable
|
||||
// -Z rustdoc-scrape-examples is unstable
|
||||
return;
|
||||
}
|
||||
|
||||
|
@ -2293,7 +2293,7 @@ fn scrape_examples_complex_reverse_dependencies() {
|
|||
.file("b/src/lib.rs", "")
|
||||
.build();
|
||||
|
||||
p.cargo("doc -Zunstable-options --scrape-examples all")
|
||||
p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
|
||||
.masquerade_as_nightly_cargo()
|
||||
.run();
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue