How to link to examples

Is there a good way to link to examples in Rust documentation?

For example, here where it says " See here for more advanced example" which currently links to my github example directory I would like to link to here (the docs.rs examples dir for the crate) but the version number will change each time I create a new version, and I don't really want to have to remember to edit the source each time.

Not sure I explained that very well, and I may not be thinking clearly here. I want some kind of documentation macro for "the examples directory for this crate".

Linking to items by name - The rustdoc book doesn't seem to help?

I don't think there's something like this yet, but would definitely like to see it happening.

In case you haven't found it yet: there's the rustdoc_scrape_examples feature that almost does that in an automated way: 3123-rustdoc-scrape-examples - The Rust RFC Book

1 Like

Thanks, I wanted to know if I was missing something. It seems not. I think your link is right when it observes:

" The participant who was less familiar with Rust struggled to read the documentation and failed to accomplish the task. By contrast, the participant who was more familiar with Rust knew to look in the examples/ directory, where they found a wealth of examples."

Indeed! I only found out about examples when I was learning about features (another thing that could use better discovery) and ended up on the Manifest Format docs. This scraping idea is excellent.

I've found it useful to create a module crate::examples with a submodule for each of the examples in examples where I give a short explanation, and maybe a link or just the comment saying code can be found in the examples directory.

Maybe one can go further, crate a unique type Example1 in crate::examples with a run method. This allows implementing the whole thing in-crate, and just having examples::example1.rs be a small shim that calls Example1::run(). That way, the code could be accessed directly in the documentation.

My version-sync crate let's you write a test which will ensure that the link is in sync with the crate version. It's not automatic, but I've found that it helps a lot by making it easy to codify such dependencies.