Auto-scrape Examples in Docs

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.

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

Navigation Menu

Repository navigation

Auto-scrape Examples in Docs #16654

What

Why

How

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	// 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
	);

Auto-scrape Examples in Docs #16654

Description

What

Why

How

Activity

alamb commented on Jul 2, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions