docs: link examples & tutorial of right version on docs.rs

[not-my-profile]

Previously the start page of the documentation on docs.rs for chumsky linked the examples and tutorial from the main branch, no matter which version you selected on docs.rs.

So e.g. https://docs.rs/chumsky/0.9.2/chumsky/ links https://github.com/zesterer/chumsky/blob/main/examples/brainfuck.rs which is confusing since the main branch currently contains the source code for the upcoming 1.0.0, which has a different API.

This commit remedies this for future releases by separating the link labels and URLs using CommonMark link reference definitions1 and overriding them in src/lib.rs, building the correct URLs via CARGO_PKG_VERSION2.

This trick will require git tags to be created for all future versions (so e.g. if 0.9.3 will be released the commit will have to be tagged with "0.9.3").

[not-my-profile]

I just realized that tutorial.md has several links to docs.rs so it would probably best to move it into a module within the crate so that the links point to the right version. An example of a project that does this is Polars (see polars::docs). However I'd rather leave this to a followup PR (if you see the merit).

[not-my-profile]

(And it would probably make sense to backport this to the legacy branch.)

[zesterer]

Thanks! Do you have any external information I could read about this technique?

Feel free to ignore tutorial.md for now, it's due to be replaced as part of the new guide anyway :)

[not-my-profile]

The technique relies on former link definitions taking precedence over latter link definitions which is specified by CommonMark, see example 204. Rustdoc uses the pulldown_cmark Markdown parser which is CommonMark compliant so this works.

[tutorial.md is] due to be replaced as part of the new guide anyway :)

Ah right ... I see that the new guide does exactly what I suggested (being part of the crate) ... so that's great :)

(updated the commit message to link this CommonMark example)

[zesterer]

Thanks! Looks like there's a small conflict to resolve before merge though.

[zesterer]

Thanks!