Auto-scrape Examples in Docs

[crepererum]

What

It's hard to put in words, but have a look at this example from bevy: https://docs.rs/bevy/0.16.1/bevy/prelude/struct.Events.html#method.send

Also see this explanation.

Why

I think the "manual style" of adding some code to the doc string is very good, e.g.:

/// Get value for given key.\
///
/// # Example
/// ```
/// ...
/// ```
pub fn get(&self, k: &str) -> Option<...> {
...

However sometimes it helps to see certain methods used in a wider context or more complex examples. While one can manually link examples, I think the rendering of rustdoc is great and avoiding manual maintenance burden is always a plus.

I think this greatly helps people to understand what certain methods do.

How

IIRC docs.rs uses a nightly compiler. So all we would need to do is to follow bevy.

[alamb]

We currently use a more manual version of this:

datafusion/datafusion/core/src/lib.rs

Lines 867 to 898 in 25c2a07

	// Instructions for Documentation Examples
	//
	// The following commands test the examples from the user guide as part of
	// `cargo test --doc`
	//
	// # Adding new tests:
	//
	// Simply add code like this to your .md file and ensure your md file is
	// included in the lists below.
	//
	// ```rust
	// <code here will be tested>
	// ```
	//
	// Note that sometimes it helps to author the doctest as a standalone program
	// first, and then copy it into the user guide.
	//
	// # Debugging Test Failures
	//
	// Unfortunately, the line numbers reported by doctest do not correspond to the
	// line numbers of in the .md files. Thus, if a doctest fails, use the name of
	// the test to find the relevant file in the list below, and then find the
	// example in that file to fix.
	//
	// For example, if `user_guide_expressions(line 123)` fails,
	// go to `docs/source/user-guide/expressions.md` to find the relevant problem.
	//
	#[cfg(doctest)]
	doc_comment::doctest!(
	"../../../docs/source/user-guide/concepts-readings-events.md",
	user_guide_concepts_readings_events
	);

Basically we use the doc_comment to manually list files to include in doc tests

It would be amazing to do it automatically with rustdocs