From 70705dfd60f27db2a24058724ad0a5abf029689d Mon Sep 17 00:00:00 2001
From: Martin Fischer <martin@push-f.com>
Date: Wed, 2 Aug 2023 15:59:33 +0200
Subject: [PATCH] docs: link examples & tutorial of right version on docs.rs

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 definitions and overriding[1]
them in src/lib.rs, building the correct URLs via CARGO_PKG_VERSION[2].

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

[1]: https://spec.commonmark.org/0.30/#example-204
[2]: https://doc.rust-lang.org/cargo/reference/environment-variables.html
---
 README.md  | 19 +++++++++++--------
 src/lib.rs | 17 +++++++++++++++++
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 57cfe846..4c71dc87 100644
--- a/README.md
+++ b/README.md
@@ -42,8 +42,7 @@ A parser library for humans with powerful error recovery.
 
 ## Example [Brainfuck](https://en.wikipedia.org/wiki/Brainfuck) Parser
 
-See [`examples/brainfuck.rs`](https://github.com/zesterer/chumsky/blob/master/examples/brainfuck.rs) for the full
-interpreter (`cargo run --example brainfuck -- examples/sample.bf`).
+See [`examples/brainfuck.rs`] for the full interpreter (`cargo run --example brainfuck -- examples/sample.bf`).
 
 ```rust
 use chumsky::prelude::*;
@@ -73,16 +72,14 @@ fn parser<'a>() -> impl Parser<'a, &'a str, Vec<Instr>> {
 
 Other examples include:
 
-- A [JSON parser](https://github.com/zesterer/chumsky/blob/master/examples/json.rs) (`cargo run --example json --
-  examples/sample.json`)
-- An [interpreter for a simple Rust-y language](https://github.com/zesterer/chumsky/blob/master/examples/nano_rust.rs)
+- A [JSON parser] (`cargo run --example json -- examples/sample.json`)
+- An [interpreter for a simple Rust-y language][examples/nano_rust.rs]
   (`cargo run --example nano_rust -- examples/sample.nrs`)
 
 ## Tutorial
 
-Chumsky has [a tutorial](https://github.com/zesterer/chumsky/blob/master/tutorial.md) that teaches you how to write a
-parser and interpreter for a simple dynamic language with unary and binary operators, operator precedence, functions,
-let declarations, and calls.
+Chumsky has a [tutorial] that teaches you how to write a parser and interpreter for a simple dynamic language
+with unary and binary operators, operator precedence, functions, let declarations, and calls.
 
 ## *What* is a parser combinator?
 
@@ -189,3 +186,9 @@ My apologies to Noam for choosing such an absurd name.
 ## License
 
 Chumsky is licensed under the MIT license (see `LICENSE` in the main repository).
+
+<!-- These link destinations are defined like this so that src/lib.rs can override them. -->
+[`examples/brainfuck.rs`]: https://github.com/zesterer/chumsky/blob/master/examples/brainfuck.rs
+[JSON parser]: https://github.com/zesterer/chumsky/blob/master/examples/json.rs
+[examples/nano_rust.rs]: https://github.com/zesterer/chumsky/blob/master/examples/nano_rust.rs
+[tutorial]: https://github.com/zesterer/chumsky/blob/master/tutorial.md
diff --git a/src/lib.rs b/src/lib.rs
index 5ff7dc38..9d4a5869 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,6 +2,14 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg), deny(rustdoc::all))]
 #![cfg_attr(feature = "nightly", feature(never_type, rustc_attrs))]
 #![cfg_attr(feature = "nightly", feature(fn_traits, tuple_trait, unboxed_closures))]
+//
+// README.md links these files via the main branch. For docs.rs we however want to link them
+// to the version of the documented crate since the files in the main branch may diverge.
+#![doc = concat!("[`examples/brainfuck.rs`]: ", blob_url_prefix!(), "/examples/brainfuck.rs")]
+#![doc = concat!("[JSON parser]: ", blob_url_prefix!(), "/examples/json.rs")]
+#![doc = concat!("[examples/nano_rust.rs]: ", blob_url_prefix!(), "/examples/nano_rust.rs")]
+#![doc = concat!("[tutorial]: ", blob_url_prefix!(), "/tutorial.md")]
+//
 #![doc = include_str!("../README.md")]
 #![deny(missing_docs, clippy::undocumented_unsafe_blocks)]
 #![allow(
@@ -13,6 +21,15 @@
 
 extern crate alloc;
 
+macro_rules! blob_url_prefix {
+    () => {
+        concat!(
+            "https://github.com/zesterer/chumsky/blob/",
+            env!("CARGO_PKG_VERSION")
+        )
+    };
+}
+
 macro_rules! go_extra {
     ( $O :ty ) => {
         #[inline(always)]