mirror of
https://github.com/rust-lang/cargo
synced 2024-09-13 04:51:31 +00:00
Change --scrape-examples flag to -Z rustdoc-scrape-examples
This commit is contained in:
parent
33718c7eef
commit
9fb78cf698
|
@ -1,7 +1,6 @@
|
||||||
use crate::command_prelude::*;
|
use crate::command_prelude::*;
|
||||||
|
|
||||||
use anyhow::anyhow;
|
use cargo::ops::{self, DocOptions};
|
||||||
use cargo::ops::{self, CompileFilter, DocOptions, FilterRule, LibRule};
|
|
||||||
|
|
||||||
pub fn cli() -> App {
|
pub fn cli() -> App {
|
||||||
subcommand("doc")
|
subcommand("doc")
|
||||||
|
@ -20,13 +19,6 @@ pub fn cli() -> App {
|
||||||
)
|
)
|
||||||
.arg(opt("no-deps", "Don't build documentation for dependencies"))
|
.arg(opt("no-deps", "Don't build documentation for dependencies"))
|
||||||
.arg(opt("document-private-items", "Document private items"))
|
.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_jobs()
|
||||||
.arg_targets_lib_bin_example(
|
.arg_targets_lib_bin_example(
|
||||||
"Document only this package's library",
|
"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)?;
|
args.compile_options(config, mode, Some(&ws), ProfileChecking::Custom)?;
|
||||||
compile_opts.rustdoc_document_private_items = args.is_present("document-private-items");
|
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 {
|
let doc_opts = DocOptions {
|
||||||
open_result: args.is_present("open"),
|
open_result: args.is_present("open"),
|
||||||
compile_opts,
|
compile_opts,
|
||||||
|
|
|
@ -654,6 +654,9 @@ unstable_cli_options!(
|
||||||
timings: Option<Vec<String>> = ("Display concurrency information"),
|
timings: Option<Vec<String>> = ("Display concurrency information"),
|
||||||
unstable_options: bool = ("Allow the usage of unstable options"),
|
unstable_options: bool = ("Allow the usage of unstable options"),
|
||||||
weak_dep_features: bool = ("Allow `dep_name?/feature` feature syntax"),
|
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),
|
skip_rustdoc_fingerprint: bool = (HIDDEN),
|
||||||
);
|
);
|
||||||
|
|
||||||
|
@ -871,6 +874,7 @@ impl CliUnstable {
|
||||||
"namespaced-features" => self.namespaced_features = parse_empty(k, v)?,
|
"namespaced-features" => self.namespaced_features = parse_empty(k, v)?,
|
||||||
"weak-dep-features" => self.weak_dep_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)?,
|
"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)?,
|
"skip-rustdoc-fingerprint" => self.skip_rustdoc_fingerprint = parse_empty(k, v)?,
|
||||||
"compile-progress" => stabilized_warn(k, "1.30", STABILIZED_COMPILE_PROGRESS),
|
"compile-progress" => stabilized_warn(k, "1.30", STABILIZED_COMPILE_PROGRESS),
|
||||||
"offline" => stabilized_err(k, "1.36", STABILIZED_OFFLINE)?,
|
"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::restricted_names::is_glob_pattern;
|
||||||
use crate::util::{closest_msg, profile, CargoResult, StableHasher};
|
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.
|
/// 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
|
/// Whether the `--document-private-items` flags was specified and should
|
||||||
/// be forwarded to `rustdoc`.
|
/// be forwarded to `rustdoc`.
|
||||||
pub rustdoc_document_private_items: bool,
|
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
|
/// Whether the build process should check the minimum Rust version
|
||||||
/// defined in the cargo metadata for a crate.
|
/// defined in the cargo metadata for a crate.
|
||||||
pub honor_rust_version: bool,
|
pub honor_rust_version: bool,
|
||||||
|
@ -97,7 +94,6 @@ impl<'a> CompileOptions {
|
||||||
target_rustc_args: None,
|
target_rustc_args: None,
|
||||||
local_rustdoc_args: None,
|
local_rustdoc_args: None,
|
||||||
rustdoc_document_private_items: false,
|
rustdoc_document_private_items: false,
|
||||||
rustdoc_scrape_examples: None,
|
|
||||||
honor_rust_version: true,
|
honor_rust_version: true,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
@ -338,7 +334,6 @@ pub fn create_bcx<'a, 'cfg>(
|
||||||
ref target_rustc_args,
|
ref target_rustc_args,
|
||||||
ref local_rustdoc_args,
|
ref local_rustdoc_args,
|
||||||
rustdoc_document_private_items,
|
rustdoc_document_private_items,
|
||||||
ref rustdoc_scrape_examples,
|
|
||||||
honor_rust_version,
|
honor_rust_version,
|
||||||
} = *options;
|
} = *options;
|
||||||
let config = ws.config();
|
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 target_data = RustcTargetData::new(ws, &build_config.requested_kinds)?;
|
||||||
|
|
||||||
let all_packages = &Packages::All;
|
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 need_reverse_dependencies = rustdoc_scrape_examples.is_some();
|
||||||
let full_specs = if need_reverse_dependencies {
|
let full_specs = if need_reverse_dependencies {
|
||||||
all_packages
|
all_packages
|
||||||
|
@ -506,7 +502,22 @@ pub fn create_bcx<'a, 'cfg>(
|
||||||
)?;
|
)?;
|
||||||
|
|
||||||
let mut scrape_units = match rustdoc_scrape_examples {
|
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_build_ids = resolve.specs_to_ids(&resolve_specs)?;
|
||||||
let to_builds = pkg_set.get_many(to_build_ids)?;
|
let to_builds = pkg_set.get_many(to_build_ids)?;
|
||||||
let mode = CompileMode::Docscrape;
|
let mode = CompileMode::Docscrape;
|
||||||
|
@ -514,7 +525,7 @@ pub fn create_bcx<'a, 'cfg>(
|
||||||
generate_targets(
|
generate_targets(
|
||||||
ws,
|
ws,
|
||||||
&to_builds,
|
&to_builds,
|
||||||
scrape_filter,
|
&filter,
|
||||||
&build_config.requested_kinds,
|
&build_config.requested_kinds,
|
||||||
explicit_host_kind,
|
explicit_host_kind,
|
||||||
mode,
|
mode,
|
||||||
|
|
|
@ -765,7 +765,6 @@ fn run_verify(
|
||||||
target_rustc_args: rustc_args,
|
target_rustc_args: rustc_args,
|
||||||
local_rustdoc_args: None,
|
local_rustdoc_args: None,
|
||||||
rustdoc_document_private_items: false,
|
rustdoc_document_private_items: false,
|
||||||
rustdoc_scrape_examples: None,
|
|
||||||
honor_rust_version: true,
|
honor_rust_version: true,
|
||||||
},
|
},
|
||||||
&exec,
|
&exec,
|
||||||
|
|
|
@ -544,7 +544,6 @@ pub trait ArgMatchesExt {
|
||||||
target_rustc_args: None,
|
target_rustc_args: None,
|
||||||
local_rustdoc_args: None,
|
local_rustdoc_args: None,
|
||||||
rustdoc_document_private_items: false,
|
rustdoc_document_private_items: false,
|
||||||
rustdoc_scrape_examples: None,
|
|
||||||
honor_rust_version: !self._is_present("ignore-rust-version"),
|
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)
|
* RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123)
|
||||||
* Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)
|
* Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)
|
||||||
|
|
||||||
The `--scrape-examples` argument to the `doc` command tells Rustdoc to search
|
The `-Z rustdoc-scrape-examples` argument tells Rustdoc to search crates in the current workspace
|
||||||
crates in the current workspace for calls to functions. Those call-sites are then
|
for calls to functions. Those call-sites are then included as documentation. The flag can take an
|
||||||
included as documentation. The flag can take an argument of `all` or `examples`
|
argument of `all` or `examples` which configures which crate in the workspace to analyze for examples.
|
||||||
which configures which crate in the workspace to analyze for examples. For instance:
|
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]
|
#[cargo_test]
|
||||||
fn scrape_examples_basic() {
|
fn scrape_examples_basic() {
|
||||||
if !is_nightly() {
|
if !is_nightly() {
|
||||||
// --scrape-examples is unstable
|
// -Z rustdoc-scrape-examples is unstable
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -2170,7 +2170,7 @@ fn scrape_examples_basic() {
|
||||||
.file("src/lib.rs", "pub fn foo() {}\npub fn bar() { foo(); }")
|
.file("src/lib.rs", "pub fn foo() {}\npub fn bar() { foo(); }")
|
||||||
.build();
|
.build();
|
||||||
|
|
||||||
p.cargo("doc -Zunstable-options --scrape-examples all")
|
p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
|
||||||
.masquerade_as_nightly_cargo()
|
.masquerade_as_nightly_cargo()
|
||||||
.with_stderr(
|
.with_stderr(
|
||||||
"\
|
"\
|
||||||
|
@ -2192,7 +2192,7 @@ fn scrape_examples_basic() {
|
||||||
#[cargo_test]
|
#[cargo_test]
|
||||||
fn scrape_examples_avoid_build_script_cycle() {
|
fn scrape_examples_avoid_build_script_cycle() {
|
||||||
if !is_nightly() {
|
if !is_nightly() {
|
||||||
// --scrape-examples is unstable
|
// -Z rustdoc-scrape-examples is unstable
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -2231,7 +2231,7 @@ fn scrape_examples_avoid_build_script_cycle() {
|
||||||
.file("bar/build.rs", "fn main(){}")
|
.file("bar/build.rs", "fn main(){}")
|
||||||
.build();
|
.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()
|
.masquerade_as_nightly_cargo()
|
||||||
.run();
|
.run();
|
||||||
}
|
}
|
||||||
|
@ -2239,7 +2239,7 @@ fn scrape_examples_avoid_build_script_cycle() {
|
||||||
#[cargo_test]
|
#[cargo_test]
|
||||||
fn scrape_examples_complex_reverse_dependencies() {
|
fn scrape_examples_complex_reverse_dependencies() {
|
||||||
if !is_nightly() {
|
if !is_nightly() {
|
||||||
// --scrape-examples is unstable
|
// -Z rustdoc-scrape-examples is unstable
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -2293,7 +2293,7 @@ fn scrape_examples_complex_reverse_dependencies() {
|
||||||
.file("b/src/lib.rs", "")
|
.file("b/src/lib.rs", "")
|
||||||
.build();
|
.build();
|
||||||
|
|
||||||
p.cargo("doc -Zunstable-options --scrape-examples all")
|
p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
|
||||||
.masquerade_as_nightly_cargo()
|
.masquerade_as_nightly_cargo()
|
||||||
.run();
|
.run();
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in a new issue