development/cargo
development/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo synced 2024-10-02 05:53:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #11425 - willcrichton:scrape-examples-documentation, r=weihanglo

Browse source 
Update documentation for -Zrustdoc-scrape-examples in the Cargo Book

### What does this PR try to resolve?

Description in the title. Fixes #11424.

### How should we test and review this PR?

Here's a screenshot of the updated documentation:

<img width="814" alt="Screen Shot 2022-11-25 at 6 24 49 PM" src="https://user-images.githubusercontent.com/663326/204065460-4e06c638-7e3d-4c00-a805-7cb4b5a3803b.png">

r? `@weihanglo`
This commit is contained in:
bors 2022-11-26 10:08:12 +00:00
parent e027c4b5d2 000725213f
commit 1382b44e43
1 changed files with 34 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
src/doc/src/reference/unstable.md
View file

@ -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)