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.

Sign up for GitHub

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

Jump to bottom

Update documentation for -Zrustdoc-scrape-examples in the Cargo Book #11425

Merged
merged 1 commit into from
Nov 26, 2022
Merged

Update documentation for -Zrustdoc-scrape-examples in the Cargo Book #11425

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 34 additions & 5 deletions src/doc/src/reference/unstable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1154,15 +1154,44 @@ path = "src/main.rs"
* RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123)
* Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)

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:
The `-Z rustdoc-scrape-examples` flag tells Rustdoc to search crates in the current workspace
for calls to functions. Those call-sites are then included as documentation. You can use the flag
like this:

```
cargo doc -Z unstable-options -Z rustdoc-scrape-examples=examples
cargo doc -Z unstable-options -Z rustdoc-scrape-examples
```

By default, Cargo will scrape from the packages that are being documented, as well as scrape from
examples for the packages (i.e. those corresponding to the `--examples` flag). You can individually
enable or disable targets from being scraped with the `doc-scrape-examples` flag, such as:

```toml
# Disable scraping examples from a library
[lib]
doc-scrape-examples = false

# Enable scraping examples from a binary
[[bin]]
name = "my-bin"
doc-scrape-examples = true
```

**Note on tests:** enabling `doc-scrape-examples` on test targets will not currently have any effect. Scraping
examples from tests is a work-in-progress.

**Note on dev-dependencies:** documenting a library does not normally require the crate's dev-dependencies. However,
example units do require dev-deps. For backwards compatibility, `-Z rustdoc-scrape-examples` will *not* introduce a
dev-deps requirement for `cargo doc`. Therefore examples will *not* be scraped from example targets under the
following conditions:

1. No target being documented requires dev-deps, AND
2. At least one crate being documented requires dev-deps, AND
3. The `doc-scrape-examples` parameter is unset for `[[example]]` targets.

If you want examples to be scraped from example targets, then you must not satisfy one of the above conditions.


### check-cfg

* RFC: [#3013](https://github.com/rust-lang/rfcs/pull/3013)
Expand Down