Change rustdoc-scrape-examples to be a target-level configuration #10343

willcrichton · 2022-01-30T23:36:02Z

This PR addresses issues raised in #9525. Specifically:

It enables examples to be scraped from #[test] functions, by passing additional flags to Rustdoc to ensure that these functions aren't ignored by rustc.
It moves the arg from -Z rustdoc-scrape-examples={arg} into a target-level configuration that can be added to Cargo.toml.

The added test scrape_examples_configure_target shows a concrete example. In short, examples will be default scraped from Example and Lib targets. Then the user can enable or disable scraping like so:

[lib]
doc-scrape-examples = false

[[test]]
name = "my_test"
doc-scrape-examples = true

camelid · 2022-01-31T02:16:06Z

Somehow I feel like it'd be better to structure the configuration as something like:

[doc]
scrape-examples-targets = ["lib", "test"]

rather than putting doc-scrape-examples in each target section. Just a gut reaction though.

willcrichton · 2022-01-31T05:43:01Z

Somehow I feel like it'd be better to structure the configuration as something like:
[doc]
scrape-examples-targets = ["lib", "test"]
rather than putting doc-scrape-examples in each target section. Just a gut reaction though.

I think the issue with this is (a) it's not consistent with existing ways to configure targets, and (b) it doesn't allow target configuration at a higher granularity. For instance, the proposed method allows you to individually enable/disable specific examples and tests, while a list of target strings can't do so.

alexcrichton · 2022-02-01T21:36:59Z

This all looks pretty reasonable to me, but I'd like to confirm my understanding. The intention is that once stabilized this is enabled for all projects by default? So all projects with libraries and examples, when using cargo doc, will see examples for methods and such drawn from libraries examples. Packages have fine-grained control at the per-target level what's used as candidates for examples and what isn't (with the default being only the lib targets and examples)

If that's the case I think it might be good to flesh out the failing tests for now. I think there may need to be some trickery around not running doc-scrape with stable Rust as-is today since Cargo tests its CI with all three channels of Rust. Otherwise though that seems pretty reasonable to me and the PR otherwise looks pretty good.

What is the right set of default targets to search for examples?

Personally the choice made here I think is fine. This seems like something we can alter over time if necessary as well.

Is there a different granularity at which example scraping should also be configurable?

At least from Cargo's perspective this probably won't have much impact, but I don't have much of an opinion on this otherwise.

As a random bikeshedding point seeing doc-scrape-examples = false in isolation feels a little surprising, so I might suggest something like doc-example-candidate = false or something like that.

GuillaumeGomez · 2022-02-01T21:44:42Z

I thought this feature would be disabled by default?

willcrichton · 2022-02-01T22:58:21Z

I thought this feature would be disabled by default?

My understanding is that it would be disabled by default while unstable, and then enabled by default once stabilized. The vast majority of people will not use this feature if it is hidden behind a flag.

GuillaumeGomez · 2022-02-01T23:09:44Z

My understanding is that it would be disabled by default while unstable, and then enabled by default once stabilized. The vast majority of people will not use this feature if it is hidden behind a flag.

Sorry, I definitely didn't understand it like this. In this case, we'll need to update the display quite a lot because it takes a lot of space by default. What about collapsing the section by default with a title like "see usage in examples" or something among the line? If you prefer we can discuss it on zulip.

willcrichton · 2022-02-01T23:42:12Z

The discussion about scraping-by-default-or-not has been pulled onto Zulip: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Enabling.20scrape.20examples.20by.20default

bors · 2022-02-22T04:48:06Z

☔ The latest upstream changes (presumably #9992) made this pull request unmergeable. Please resolve the merge conflicts.

lqd · 2022-03-28T07:17:25Z

@willcrichton The .rustfmt.toml change and new log file, seem unintentional.

willcrichton · 2022-03-28T15:42:58Z

Ah thanks @lqd , got caught up in the rebase. I'll squash everything in a bit.

bors · 2022-04-04T15:10:07Z

☔ The latest upstream changes (presumably #10533) made this pull request unmergeable. Please resolve the merge conflicts.

willcrichton · 2022-04-14T00:52:22Z

This PR is ready for review, although it needs a new Cargo reviewer since Alex has stepped back (is there a way to nominate a new reviewer?)

As a reminder, this PR will enable the scrape examples feature by default, although only when run with a nightly rustc. Now that rust-lang/rust#93217 has landed, I think this feature is ready to be rolled out at least on docs.rs. Rustdoc maintainers, please let me know if you have any remaining concerns about this feature.

cc @jsha @camelid @GuillaumeGomez

@rustbot ready

willcrichton · 2022-04-15T19:55:11Z

It seems like only @ehuss is on reviewer rotation for Cargo right now, so I will add him. Sorry for all the extra work Eric :(

r? @ehuss

weihanglo · 2022-11-25T06:58:14Z

@bors retry

bors · 2022-11-25T06:58:22Z

⌛ Testing commit 183425f with merge de56c12...

bors · 2022-11-25T07:44:02Z

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing de56c12 to master...

5 commits in ba607b23db8398723d659249d9abf5536bc322e5..e027c4b5d25af2119b1956fac42863b9b3242744 2022-11-22 20:52:39 +0000 to 2022-11-25 19:44:46 +0000 - fix: Move off atty to resolve soundness issue (rust-lang/cargo#11420) - add newline char to `cargo install .` error message for easier reading. (rust-lang/cargo#11401) - chore: Upgrade to env_logger (rust-lang/cargo#11417) - Change rustdoc-scrape-examples to be a target-level configuration (rust-lang/cargo#10343) - temporarily disable test `lto::test_profile` (rust-lang/cargo#11419)

Update cargo 5 commits in ba607b23db8398723d659249d9abf5536bc322e5..e027c4b5d25af2119b1956fac42863b9b3242744 2022-11-22 20:52:39 +0000 to 2022-11-25 19:44:46 +0000 - fix: Move off atty to resolve soundness issue (rust-lang/cargo#11420) - add newline char to `cargo install .` error message for easier reading. (rust-lang/cargo#11401) - chore: Upgrade to env_logger (rust-lang/cargo#11417) - Change rustdoc-scrape-examples to be a target-level configuration (rust-lang/cargo#10343) - temporarily disable test `lto::test_profile` (rust-lang/cargo#11419) r+ `@ghost`

5 commits in ba607b23db8398723d659249d9abf5536bc322e5..e027c4b5d25af2119b1956fac42863b9b3242744 2022-11-22 20:52:39 +0000 to 2022-11-25 19:44:46 +0000 - fix: Move off atty to resolve soundness issue (rust-lang/cargo#11420) - add newline char to `cargo install .` error message for easier reading. (rust-lang/cargo#11401) - chore: Upgrade to env_logger (rust-lang/cargo#11417) - Change rustdoc-scrape-examples to be a target-level configuration (rust-lang/cargo#10343) - temporarily disable test `lto::test_profile` (rust-lang/cargo#11419)

Update cargo 5 commits in ba607b23db8398723d659249d9abf5536bc322e5..e027c4b5d25af2119b1956fac42863b9b3242744 2022-11-22 20:52:39 +0000 to 2022-11-25 19:44:46 +0000 - fix: Move off atty to resolve soundness issue (rust-lang/cargo#11420) - add newline char to `cargo install .` error message for easier reading. (rust-lang/cargo#11401) - chore: Upgrade to env_logger (rust-lang/cargo#11417) - Change rustdoc-scrape-examples to be a target-level configuration (rust-lang/cargo#10343) - temporarily disable test `lto::test_profile` (rust-lang/cargo#11419) r+ `@ghost`

We were broken by rust-lang/cargo#10343. See rust-lang/cargo#11425 Fixes #4519

Improve strategy for selecting targets to be scraped for examples ### What does this PR try to resolve? After #10343, we have identified a clear set of conditions for whether a particular target should be considered by `-Zrustdoc-scrape-examples`. These conditions are described more clearly in #11425. However, after some testing with complex Cargo workspaces (e.g. [wasmtime](https://github.com/bytecodealliance/wasmtime/)), I realized that the current approach of modifying the `CompileFilter` did not correctly implement this new specification. For example, a target with `doc = false` should not be scraped by default since it is not a documented unit, but the current approach would potentially include such a target for scraping. This PR provides a new approach which I believe correctly implements the specification: 1. `generate_targets` is called with the same parameters except the `mode` which becomes `CompileMode::Docscrape` instead of `CompileMode::Doc`. `filter_default_targets` generates the same targets for `Docscrape` as for `Doc`. 2. Inside `generate_targets`, an initial set of `Proposal`s are created. This set of proposals is extended with further proposals based on targets identified as `doc-scrape-examples = true`, or Example targets where possible. This PR subsumes #11423, and also fixes #10571. ### How should we test and review this PR? I have added another test `docscrape::only_scrape_documented_targets` to verify that only documented or explicitly-enabled targets are included for scraping. r? `@weihanglo`

Update cargo 5 commits in ba607b23db8398723d659249d9abf5536bc322e5..e027c4b5d25af2119b1956fac42863b9b3242744 2022-11-22 20:52:39 +0000 to 2022-11-25 19:44:46 +0000 - fix: Move off atty to resolve soundness issue (rust-lang/cargo#11420) - add newline char to `cargo install .` error message for easier reading. (rust-lang/cargo#11401) - chore: Upgrade to env_logger (rust-lang/cargo#11417) - Change rustdoc-scrape-examples to be a target-level configuration (rust-lang/cargo#10343) - temporarily disable test `lto::test_profile` (rust-lang/cargo#11419) r+ `@ghost`

Enable triagebot's relabel functionality ### What does this PR try to resolve? This fixes the following failure that rustbot currently posts whenever someone tries to use "`@rustbot` label" in this repository. > **Error**: The feature `relabel` is not enabled in this repository. > To enable it add its section in the `triagebot.toml` in the root of the repository. Unauthenticated relabel has been enabled in rust-lang/rust for nearly 4 years. People overwhelmingly use it in good faith. ### How should we test and review this PR? Compare against https://github.com/rust-lang/rust/blob/1.66.0/triagebot.toml. Also skim through the 7 pages of labels on https://github.com/rust-lang/cargo/labels, whether it makes sense the ones I decided to allow arbitrary GitHub users to apply. ### Additional information Attempted uses of "`@rustbot` label", that failed, but this PR would allow: - #10343 (comment) - #10243 (comment) - #9982 (comment) - #9128 (comment) - #9067 (comment) - #8441 (comment) - #11432 (comment) - #8841 (comment) - #10820 (comment) - #10572 (comment) - #9114 (comment) - #8980 (comment) - #9064 (comment) - #8726 (comment) - #8089 (comment)

rust-highfive assigned alexcrichton Jan 30, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2022

alexcrichton added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 2, 2022

willcrichton force-pushed the example-analyzer branch from 78045d4 to 64ffa4f Compare February 2, 2022 18:28

This was referenced Feb 2, 2022

Tracking Issue for RFC 3123: Scrape code examples from examples/ directory for Rustdoc rust-lang/rust#88791

Open

Add --scrape-tests option to rustdoc to scrape functions marked #[test] rust-lang/rust#93497

Merged

alexcrichton removed their assignment Mar 8, 2022

willcrichton force-pushed the example-analyzer branch from 64ffa4f to d20ab08 Compare March 28, 2022 02:22

willcrichton mentioned this pull request Mar 28, 2022

-Z rustdoc-scrape-examples panics with some profile overrides #10500

Closed

willcrichton force-pushed the example-analyzer branch from e74509e to 8ea5efa Compare March 28, 2022 03:04

lqd mentioned this pull request Mar 29, 2022

Turn off debuginfo for build dependencies to improve compile times #10493

Closed

3 tasks

willcrichton force-pushed the example-analyzer branch 2 times, most recently from 836e9f1 to 1daaf68 Compare April 14, 2022 00:46

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. labels Apr 14, 2022

willcrichton mentioned this pull request Apr 15, 2022

Cargo panics when using -Z rustdoc-scrape-examples=examples on proc-macro crates #10571

Closed

bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Nov 24, 2022

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 25, 2022

bors merged commit de56c12 into rust-lang:master Nov 25, 2022

weihanglo mentioned this pull request Nov 25, 2022

scrape-examples does not fingerprint correctly #10876

Closed

willcrichton mentioned this pull request Nov 25, 2022

cargo doc rustdoc-scrape-examples failure #10865

Open

weihanglo mentioned this pull request Nov 25, 2022

Document new default of -Zrustdoc-scrape-examples #11424

Closed

weihanglo mentioned this pull request Nov 25, 2022

Update cargo rust-lang/rust#104915

Merged

This was referenced Nov 27, 2022

Fix UI issues with Rustdoc scrape-examples feature. rust-lang/rust#104967

Merged

Improve strategy for selecting targets to be scraped for examples #11430

Merged

epage added a commit to clap-rs/clap that referenced this pull request Nov 29, 2022

docs: Fix docs.rs builds

6e31743

We were broken by rust-lang/cargo#10343. See rust-lang/cargo#11425 Fixes #4519

MoAlyousef mentioned this pull request Dec 2, 2022

[BUG] fltk 1.3.22 fails to build documentation fltk-rs/fltk-rs#1322

Closed

Emilgardis mentioned this pull request Dec 3, 2022

replace actions-rs twitch-rs/twitch_oauth2#100

Merged

willcrichton mentioned this pull request Dec 13, 2022

Add -Zrustdoc-scrape-examples to default Cargo args rust-lang/docs.rs#1954

Merged

ehuss added this to the 1.67.0 milestone Dec 14, 2022

dtolnay mentioned this pull request Dec 18, 2022

Enable triagebot's relabel functionality #11498

Merged

weihanglo mentioned this pull request Dec 27, 2022

Tracking Issue for doc --scrape-examples #9910

Open

valkum mentioned this pull request Feb 1, 2023

Docs are not building on docs.rs arlyon/async-stripe#333

Closed

weihanglo added the Z-scrape-examples Nightly: rustdoc scrape examples label Sep 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Change rustdoc-scrape-examples to be a target-level configuration #10343

Change rustdoc-scrape-examples to be a target-level configuration #10343

willcrichton commented Jan 30, 2022 •

edited

Loading

camelid commented Jan 31, 2022 •

edited

Loading

willcrichton commented Jan 31, 2022

alexcrichton commented Feb 1, 2022

GuillaumeGomez commented Feb 1, 2022

willcrichton commented Feb 1, 2022 •

edited

Loading

GuillaumeGomez commented Feb 1, 2022

willcrichton commented Feb 1, 2022

bors commented Feb 22, 2022

lqd commented Mar 28, 2022

willcrichton commented Mar 28, 2022

bors commented Apr 4, 2022

willcrichton commented Apr 14, 2022 •

edited

Loading

willcrichton commented Apr 15, 2022

weihanglo commented Nov 25, 2022

bors commented Nov 25, 2022

bors commented Nov 25, 2022

Change rustdoc-scrape-examples to be a target-level configuration #10343

Change rustdoc-scrape-examples to be a target-level configuration #10343

Conversation

willcrichton commented Jan 30, 2022 • edited Loading

camelid commented Jan 31, 2022 • edited Loading

willcrichton commented Jan 31, 2022

alexcrichton commented Feb 1, 2022

GuillaumeGomez commented Feb 1, 2022

willcrichton commented Feb 1, 2022 • edited Loading

GuillaumeGomez commented Feb 1, 2022

willcrichton commented Feb 1, 2022

bors commented Feb 22, 2022

lqd commented Mar 28, 2022

willcrichton commented Mar 28, 2022

bors commented Apr 4, 2022

willcrichton commented Apr 14, 2022 • edited Loading

willcrichton commented Apr 15, 2022

weihanglo commented Nov 25, 2022

bors commented Nov 25, 2022

bors commented Nov 25, 2022

willcrichton commented Jan 30, 2022 •

edited

Loading

camelid commented Jan 31, 2022 •

edited

Loading

willcrichton commented Feb 1, 2022 •

edited

Loading

willcrichton commented Apr 14, 2022 •

edited

Loading