Allow scraping examples from library

Author: willcrichton

src/bin/cargo/commands/doc.rs

@@ -1,6 +1,7 @@
 use crate::command_prelude::*;
 
-use cargo::ops::{self, DocOptions};
+use anyhow::anyhow;
+use cargo::ops::{self, CompileFilter, DocOptions, FilterRule, LibRule};
 
 pub fn cli() -> App {
     subcommand("doc")
@@ -19,10 +20,13 @@ 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 from examples/ directory to include as function documentation",
-        ))
+        .arg(
+            opt(
+                "scrape-examples",
+                "Scrape examples from examples/ directory to include as function documentation",
+            )
+            .value_name("FLAGS"),
+        )
         .arg_jobs()
         .arg_targets_lib_bin_example(
             "Document only this package's library",
@@ -51,9 +55,35 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let mut compile_opts =
         args.compile_options(config, mode, Some(&ws), ProfileChecking::Custom)?;
     compile_opts.rustdoc_document_private_items = args.is_present("document-private-items");
-    compile_opts.rustdoc_scrape_examples = args.is_present("scrape-examples");
+    compile_opts.rustdoc_scrape_examples = match args.value_of("scrape-examples") {
+        Some(s) => {
+            let (examples, lib) = match s {
+                "all" => (true, true),
+                "examples" => (true, false),
+                "lib" => (false, true),
+                _ => {
+                    return Err(CliError::from(anyhow!(
+                        r#"--scrape-examples must take "all", "examples", or "lib" as an argument"#
+                    )));
+                }
+            };
+            Some(CompileFilter::Only {
+                all_targets: false,
+                lib: if lib { LibRule::True } else { LibRule::False },
+                bins: FilterRule::none(),
+                examples: if examples {
+                    FilterRule::All
+                } else {
+                    FilterRule::none()
+                },
+                benches: FilterRule::none(),
+                tests: FilterRule::none(),
+            })
+        }
+        None => None,
+    };
 
-    if compile_opts.rustdoc_scrape_examples {
+    if compile_opts.rustdoc_scrape_examples.is_some() {
         // FIXME(wcrichto): add a tracking issue once this gets merged and add issue number below
         config
             .cli_unstable()

src/cargo/ops/cargo_compile.rs

@@ -80,7 +80,7 @@ pub struct CompileOptions {
     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: bool,
+    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,
@@ -99,7 +99,7 @@ impl<'a> CompileOptions {
             target_rustc_args: None,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: false,
+            rustdoc_scrape_examples: None,
             honor_rust_version: true,
         })
     }
@@ -231,7 +231,7 @@ impl Packages {
     }
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, PartialEq, Eq, Clone)]
 pub enum LibRule {
     /// Include the library, fail if not present
     True,
@@ -241,13 +241,13 @@ pub enum LibRule {
     False,
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub enum FilterRule {
     All,
     Just(Vec<String>),
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub enum CompileFilter {
     Default {
         /// Flag whether targets can be safely skipped when required-features are not satisfied.
@@ -340,7 +340,7 @@ pub fn create_bcx<'a, 'cfg>(
         ref target_rustc_args,
         ref local_rustdoc_args,
         rustdoc_document_private_items,
-        rustdoc_scrape_examples,
+        ref rustdoc_scrape_examples,
         honor_rust_version,
     } = *options;
     let config = ws.config();
@@ -593,21 +593,14 @@ pub fn create_bcx<'a, 'cfg>(
         }
     }
 
-    if rustdoc_scrape_examples {
+    if let Some(filter) = rustdoc_scrape_examples {
         let compile_mode = CompileMode::Doc { deps: false };
         let mut example_compile_opts = CompileOptions::new(ws.config(), compile_mode)?;
         example_compile_opts.cli_features = options.cli_features.clone();
         example_compile_opts.build_config.mode = compile_mode;
         example_compile_opts.spec = Packages::All;
-        example_compile_opts.filter = CompileFilter::Only {
-            all_targets: false,
-            lib: LibRule::False,
-            bins: FilterRule::none(),
-            examples: FilterRule::All,
-            benches: FilterRule::none(),
-            tests: FilterRule::none(),
-        };
-        example_compile_opts.rustdoc_scrape_examples = false;
+        example_compile_opts.filter = filter.clone();
+        example_compile_opts.rustdoc_scrape_examples = None;
 
         let exec: Arc<dyn Executor> = Arc::new(DefaultExecutor);
         let interner = UnitInterner::new();

src/cargo/ops/cargo_package.rs

@@ -765,7 +765,7 @@ fn run_verify(
             target_rustc_args: rustc_args,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: false,
+            rustdoc_scrape_examples: None,
             honor_rust_version: true,
         },
         &exec,

src/cargo/util/command_prelude.rs

@@ -544,7 +544,7 @@ pub trait ArgMatchesExt {
             target_rustc_args: None,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: false,
+            rustdoc_scrape_examples: None,
             honor_rust_version: !self._is_present("ignore-rust-version"),
         };