apache / apache/datafusion

Auto-scrape Examples in Docs

Open
#16,654 1 comment 2 reactions 0 assignees View on GitHub
documentation
Dominant language
Rust
Stars
9.3k
Forks
2.4k
Avg merge
3d 7h
Merged PRs (30d)
344

Description

# 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

![Image](https://github.com/user-attachments/assets/d7b95882-3784-4b6b-9364-5974face97c6)

Also see [this explanation](https://docs.rs/bevy/0.16.1/scrape-examples-help.html).

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

```rust
/// 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](https://docs.rs/) uses a nightly compiler. So all we would need to do is to [follow `bevy`](https://github.com/bevyengine/bevy/blob/1a410efd246e0f2f41766d47e300f474c8379b2e/Cargo.toml#L4357).

Contributor guide

Open the contributing guide

Research direction

Start with the linked Bevy example, the docs.rs scrape-examples-help explanation, and the referenced Cargo.toml dependency. Investigate how rustdoc and docs.rs could support automatically scraped examples without manual links. Done means the approach is implemented and documented well enough for wider-context examples to render reliably.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.