From fbbcb089c52e6dce88600be36a1cc97884294d4f Mon Sep 17 00:00:00 2001 From: Will Crichton Date: Fri, 11 Feb 2022 21:48:59 -0800 Subject: [PATCH] Add --scrape-tests flags so rustdoc can scrape examples from tests --- src/doc/rustdoc/src/unstable-features.md | 3 +++ src/librustdoc/core.rs | 3 +++ src/librustdoc/lib.rs | 3 +++ src/librustdoc/scrape_examples.rs | 15 +++++++++++---- .../rustdoc-scrape-examples-multiple/scrape.mk | 3 ++- .../rustdoc-scrape-examples-test/Makefile | 6 ++++++ .../rustdoc-scrape-examples-test/examples/ex.rs | 6 ++++++ .../rustdoc-scrape-examples-test/src/lib.rs | 3 +++ 8 files changed, 37 insertions(+), 5 deletions(-) create mode 100644 src/test/run-make/rustdoc-scrape-examples-test/Makefile create mode 100644 src/test/run-make/rustdoc-scrape-examples-test/examples/ex.rs create mode 100644 src/test/run-make/rustdoc-scrape-examples-test/src/lib.rs diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index d60be193bda2b..c7fd5ed6fcb2e 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -509,3 +509,6 @@ reverse-dependency like `examples/ex.rs` is given to rustdoc with the target crate being documented (`foobar`) and a path to output the calls (`output.calls`). Then, the generated calls file can be passed via `--with-examples` to the subsequent documentation of `foobar`. + +To scrape examples from test code, e.g. functions marked `#[test]`, then +add the `--scrape-tests` flag. diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 1f14a333c005d..955572850c6e8 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -200,6 +200,7 @@ crate fn create_config( lint_opts, describe_lints, lint_cap, + scrape_examples_options, .. }: RustdocOptions, ) -> rustc_interface::Config { @@ -227,6 +228,7 @@ crate fn create_config( let crate_types = if proc_macro_crate { vec![CrateType::ProcMacro] } else { vec![CrateType::Rlib] }; + let test = scrape_examples_options.map(|opts| opts.scrape_tests).unwrap_or(false); // plays with error output here! let sessopts = config::Options { maybe_sysroot, @@ -244,6 +246,7 @@ crate fn create_config( edition, describe_lints, crate_name, + test, ..Options::default() }; diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 68028604fa463..dbd0168284251 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -596,6 +596,9 @@ fn opts() -> Vec { "collect function call information for functions from the target crate", ) }), + unstable("scrape-tests", |o| { + o.optflag("", "scrape-tests", "Include test code when scraping examples") + }), unstable("with-examples", |o| { o.optmulti( "", diff --git a/src/librustdoc/scrape_examples.rs b/src/librustdoc/scrape_examples.rs index 16882cf83d09c..80292b208663d 100644 --- a/src/librustdoc/scrape_examples.rs +++ b/src/librustdoc/scrape_examples.rs @@ -34,6 +34,7 @@ use std::path::PathBuf; crate struct ScrapeExamplesOptions { output_path: PathBuf, target_crates: Vec, + crate scrape_tests: bool, } impl ScrapeExamplesOptions { @@ -43,16 +44,22 @@ impl ScrapeExamplesOptions { ) -> Result, i32> { let output_path = matches.opt_str("scrape-examples-output-path"); let target_crates = matches.opt_strs("scrape-examples-target-crate"); - match (output_path, !target_crates.is_empty()) { - (Some(output_path), true) => Ok(Some(ScrapeExamplesOptions { + let scrape_tests = matches.opt_present("scrape-tests"); + match (output_path, !target_crates.is_empty(), scrape_tests) { + (Some(output_path), true, _) => Ok(Some(ScrapeExamplesOptions { output_path: PathBuf::from(output_path), target_crates, + scrape_tests, })), - (Some(_), false) | (None, true) => { + (Some(_), false, _) | (None, true, _) => { diag.err("must use --scrape-examples-output-path and --scrape-examples-target-crate together"); Err(1) } - (None, false) => Ok(None), + (None, false, true) => { + diag.err("must use --scrape-examples-output-path and --scrape-examples-target-crate with --scrape-tests"); + Err(1) + } + (None, false, false) => Ok(None), } } } diff --git a/src/test/run-make/rustdoc-scrape-examples-multiple/scrape.mk b/src/test/run-make/rustdoc-scrape-examples-multiple/scrape.mk index 1fa1fae1a0b71..d49b6c1f290cb 100644 --- a/src/test/run-make/rustdoc-scrape-examples-multiple/scrape.mk +++ b/src/test/run-make/rustdoc-scrape-examples-multiple/scrape.mk @@ -7,7 +7,8 @@ $(TMPDIR)/%.calls: $(TMPDIR)/libfoobar.rmeta --extern foobar=$(TMPDIR)/libfoobar.rmeta \ -Z unstable-options \ --scrape-examples-output-path $@ \ - --scrape-examples-target-crate foobar + --scrape-examples-target-crate foobar \ + $(extra_flags) $(TMPDIR)/lib%.rmeta: src/lib.rs $(RUSTC) src/lib.rs --crate-name $* --crate-type lib --emit=metadata diff --git a/src/test/run-make/rustdoc-scrape-examples-test/Makefile b/src/test/run-make/rustdoc-scrape-examples-test/Makefile new file mode 100644 index 0000000000000..9f80a8d96022f --- /dev/null +++ b/src/test/run-make/rustdoc-scrape-examples-test/Makefile @@ -0,0 +1,6 @@ +extra_flags := --scrape-tests +deps := ex + +-include ../rustdoc-scrape-examples-multiple/scrape.mk + +all: scrape diff --git a/src/test/run-make/rustdoc-scrape-examples-test/examples/ex.rs b/src/test/run-make/rustdoc-scrape-examples-test/examples/ex.rs new file mode 100644 index 0000000000000..d1a9a74e7825c --- /dev/null +++ b/src/test/run-make/rustdoc-scrape-examples-test/examples/ex.rs @@ -0,0 +1,6 @@ +fn main() {} + +#[test] +fn a_test() { + foobar::ok(); +} diff --git a/src/test/run-make/rustdoc-scrape-examples-test/src/lib.rs b/src/test/run-make/rustdoc-scrape-examples-test/src/lib.rs new file mode 100644 index 0000000000000..22be1ad41010f --- /dev/null +++ b/src/test/run-make/rustdoc-scrape-examples-test/src/lib.rs @@ -0,0 +1,3 @@ +// @has foobar/fn.ok.html '//*[@class="docblock scraped-example-list"]' '' + +pub fn ok() {}