How to link to examples

help
1

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".

https://doc.rust-lang.org/rustdoc/linking-to-items-by-name.html doesn't seem to help?

2

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
3

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."

4

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.

5

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.

6

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.

7

I may well be missing something, but I don't see how that works for this. The version string has to be in a documentation comment, and as I understand it I cannot have macros or anything there?

8

Yeah, you are right, you cannot add a special tag to the documentation. But you can add a test which will alert you if you forget to update the link.

To do this, you would create a file named tests/documentation.rs or similar and add a test looking like this:

#[test]
fn test_axumtest_example_link_is_updated() {
    version_sync::assert_contains_substring!(
        "src/lib.rs",
        "//![See here](https://docs.rs/crate/rustdb/{version}/source/examples/axumtest.rs)"
    );
}

The {version} placeholder is replaced with the crate version, currently 0.1.25.

When you run cargo test, you now see a test failure:

running 1 test
test test_axumtest_example_link_is_updated ... FAILED

failures:

---- test_axumtest_example_link_is_updated stdout ----
Searching for "//![See here](https://docs.rs/crate/rustdb/{version}/source/examples/axumtest.rs)" in src/lib.rs...
thread 'test_axumtest_example_link_is_updated' panicked at 'could not find "//![See here](https://docs.rs/crate/rustdb/0.1.25/source/examples/axumtest.rs)" in src/lib.rs', tests/documentation.rs:3:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    test_axumtest_example_link_is_updated

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

That's all :slight_smile: You will now always have to update the link in lock-step with bumping the version number (assuming you run tests when you bump the version number).

The version-sync crate has some very simple helpers which you could easily write yourself—but it also has some more complex helpers for parsing TOML code in README files (if you like, it's all optional).

9

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.