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")
)
.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",
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,
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),
);
"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)?,
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.
///
/// 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,
target_rustc_args: None,
local_rustdoc_args: None,
rustdoc_document_private_items: false,
- rustdoc_scrape_examples: None,
honor_rust_version: true,
})
}
ref target_rustc_args,
ref local_rustdoc_args,
rustdoc_document_private_items,
- ref rustdoc_scrape_examples,
honor_rust_version,
} = *options;
let config = ws.config();
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
)?;
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;
generate_targets(
ws,
&to_builds,
- scrape_filter,
+ &filter,
&build_config.requested_kinds,
explicit_host_kind,
mode,
target_rustc_args: rustc_args,
local_rustdoc_args: None,
rustdoc_document_private_items: false,
- rustdoc_scrape_examples: None,
honor_rust_version: true,
},
&exec,
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"),
};
* 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
```
#[cargo_test]
fn scrape_examples_basic() {
if !is_nightly() {
- // --scrape-examples is unstable
+ // -Z rustdoc-scrape-examples is unstable
return;
}
.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(
"\
#[cargo_test]
fn scrape_examples_avoid_build_script_cycle() {
if !is_nightly() {
- // --scrape-examples is unstable
+ // -Z rustdoc-scrape-examples is unstable
return;
}
.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();
}
#[cargo_test]
fn scrape_examples_complex_reverse_dependencies() {
if !is_nightly() {
- // --scrape-examples is unstable
+ // -Z rustdoc-scrape-examples is unstable
return;
}
.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();
}