Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add -Zrustdoc-scrape-examples to default Cargo args #1954

Merged
merged 1 commit into from
Dec 16, 2022

Conversation

willcrichton
Copy link
Contributor

@willcrichton willcrichton commented Dec 13, 2022

This PR adds -Zrustdoc-scrape-examples to the set of default arguments passed to cargo doc. This (finally!) enables the scrape-examples feature to be enabled by default for all readers of docs.rs.

After extensive work within Cargo (rust-lang/cargo#10343, rust-lang/cargo#10533, rust-lang/cargo#10549, rust-lang/cargo#11430, rust-lang/cargo#11450), this option is now robust enough to avoid breaking any existing build. Any crate that documented before will still document with -Zrustdoc-scrape-examples. The core issue that was addressed is to not require dev-dependencies if they weren't already needed.

I have verified that -Zrustdoc-scrape-examples does not introduce breakage in a recent Crater run: https://crater-reports.s3.amazonaws.com/scrape-examples/index.html
(Note there are regressions, but they appear to be spurious and not related to the scrape-examples feature.)

This PR is currently a draft because I am waiting on rust-lang/cargo#11450 to reach nightly in a few days. But I wanted to put it up before then to provide room for discussion if someone is not comfortable enabling this flag.

cc @jyn514 @GuillaumeGomez @jsha

@github-actions github-actions bot added the S-waiting-on-review Status: This pull request has been implemented and needs to be reviewed label Dec 13, 2022
@willcrichton willcrichton marked this pull request as ready for review December 16, 2022 01:14
@willcrichton
Copy link
Contributor Author

Now that rust-lang/rust@fb0ca59 has landed in nightly, this PR is ready for review.

@jyn514
Copy link
Member

jyn514 commented Dec 16, 2022

@willcrichton can you clarify for me where we ended up with the defaults? Is this bit still true? rust-lang/cargo#10343 (comment)

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 so, that seems good to me :) thank you for all your hard work pushing this feature through!

@willcrichton
Copy link
Contributor Author

@jyn514 yes that's right. The longer explanation currently lives on the Unstable Features page in the Cargo book: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#scrape-examples

And thank you! Really excited to see this feature make it out in the world.

@syphar
Copy link
Member

syphar commented Dec 16, 2022

@jyn514 so this can be approved & merged?

@jyn514
Copy link
Member

jyn514 commented Dec 16, 2022

Yup!

@jyn514 jyn514 merged commit 42e661a into rust-lang:master Dec 16, 2022
@github-actions github-actions bot added S-waiting-on-deploy This PR is ready to be merged, but is waiting for an admin to have time to deploy it and removed S-waiting-on-review Status: This pull request has been implemented and needs to be reviewed labels Dec 16, 2022
@syphar syphar removed the S-waiting-on-deploy This PR is ready to be merged, but is waiting for an admin to have time to deploy it label Dec 17, 2022
arlyon added a commit to arlyon/async-stripe that referenced this pull request Feb 4, 2023
Closes #333. Rustdoc examples scraping is now turned on by default. rust-lang/docs.rs#1954
@arlyon arlyon mentioned this pull request Feb 4, 2023
2 tasks
Gmanboy added a commit to Gmanboy/async-stripe that referenced this pull request Aug 12, 2024
Closes #333. Rustdoc examples scraping is now turned on by default. rust-lang/docs.rs#1954
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants