rustdoc: Tracking issue for scraping code examples from the `examples/` directory

[camelid]

This is a tracking issue for the RFC 3123 | Scrape code examples from examples/ directory for Rustdoc.

Note

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.

A tracking issue is however not meant for large scale discussion, questions, or bug reports.
Instead, open a dedicated issue for the specific matter or post in the #t-rustdoc Zulip channel.

Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Steps

• Implement the RFC (Scrape code examples from examples/ directory for Rustdoc #85833 and Scrape code examples from examples/ directory for Rustdoc cargo#9525)
• Allow users to (unstably) enable on docs.rs (no changes needed)
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

1. Is showing 1 example by default the best idea? Or should scraped examples be hidden by default?
2. Is the ability to see the full file context worth the increase in page size?
3. How should the examples be ordered? Is there a way to determine the "best" examples to show first?

Implementation history

• Scrape code examples from examples/ directory for Rustdoc #85833
• Scrape code examples from examples/ directory for Rustdoc cargo#9525

[alexcrichton]

I left a comment on the Cargo PR but to summarize here, I don't think that the current cargo doc --scrape-examples interface (requesting this via the CLI) is the best way to stabilize an interface into this through Cargo. Instead I think that it would be better to support this configuration via the manifest where targets (e.g. libraries, binaries, etc) can each individually be configured whether or not they are considered candidates for scraping examples. That will change part of the Cargo implementation (but not all) in a way that I don't expect to be too radical but probably still a chunk of work to get done before final stabilization.

[camelid]

That will change part of the Cargo implementation (but not all) in a way that I don't expect to be too radical but probably still a chunk of work to get done before final stabilization.

Yeah, we'll still want to test this feature for a while before stabilizing, so we have time :)

[vicky5124]

Some crates make rustdoc panic with this feature being used, a couple of these are:

serenity, which leads to these logs: https://pastebin.com/smwdrWbD
Using a relatively standard cargo doc command:
RUST_BACKTRACE=full RUSTDOCFLAGS="--cfg docsrs -D rustdoc::broken_intra_doc_links" cargo +nightly doc -Z unstable-options -Z rustdoc-scrape-examples=all --open --no-deps --all-features

A similar issue happens with lavalink-rs, where the serenity example panics rustdoc with these logs: https://pastebin.com/sHJ0YZh6
But if it's removed from the workspaces on Cargo.toml, it compiles with the twilight example, but with an issue: none of the methods used in the example show up in the docs.

To show that this is not an issue strictly with serenity, poise, a library which depends on serenity, uses it on its examples, and re-exports it, does not have this issue, as show by it having its docs built this way.

Note: rustdoc-scrape-examples=all is used instead of rustdoc-scrape-examples=examples because both of the libraries with issues use subcrates as examples; I thought this was the reason as to why the panic happens, but a minimal crate with the same kind of examples worked just fine. I also tried to see if proc-macros were causing the panic, but that's not the case either.

[willcrichton]

@vicky5124 thanks for the bug reports. I have fixed these issues (macro-related) in #90583 which should hopefully land by the time today's nightly (2021-11-05) is released.

[programatik29]

I did a quick test.

Scraping examples with this Cargo.toml does not work:

[package]
name = "scrape-me"
version = "0.1.0"
edition = "2021"

[dependencies]

This works:

[package]
name = "scrape_me" # '_' instead of '-'
version = "0.1.0"
edition = "2021"

[dependencies]

[willcrichton]

@programatik29 thanks for the report. This is issue rust-lang/cargo#10035 which has been fixed in rust-lang/cargo#10037. We just have to wait for the cargo submodule in rustc to get updated (cc @ehuss).

[programatik29]

Nice. This feature is amazing. Can't wait to use it in my docs.

[PicoJr]

Building doc locally works fine

cargo +nightly doc -Z unstable-options -Z rustdoc-scrape-examples=examples

does pick up the right code snippet from my examples/ folder for my crate htp.

It looks great btw.

Online rustdoc (does not seem to work with my crate)

I have not managed to have my crate's doc benefit from this new feature, here is my Cargo.toml:

https://github.com/PicoJr/htp/blob/6faea37ad8f1c63a9992d16391389fda5d79011d/Cargo.toml#L21-L23

I use the section described here.

(edit) Could it be because of the include section of my Cargo.toml? here are the doc build logs for my crate: https://docs.rs/crate/htp/0.4.1/builds/459893

[willcrichton]

@PicoJr yes, it is your include section. docs.rs will download the published version of your crate, and if the examples aren't included, then they can't be scraped.

Note to everyone reading this: if you see the following warning in your cargo doc logs, then your examples are either misconfigured or not published:

Warning: Target filter `examples` specified, but no targets matched. This is a no-op

[PicoJr]

@PicoJr yes, it is your include section. docs.rs will download the published version of your crate, and if the examples aren't included, then they can't be scraped.

Note to everyone reading this: if you see the following warning in your cargo doc logs, then your examples are either misconfigured or not published:

Warning: Target filter `examples` specified, but no targets matched. This is a no-op

@willcrichton thanks for your reply it does work now.