Automatically generate rustdocs links to references in markdown

.github/workflows/rust.yml

@@ -42,9 +42,17 @@ jobs:
       - name: Cache Cargo registry
         uses: Swatinem/rust-cache@v2
 
+      - name: Install cargo-nextest
+        uses: taiki-e/install-action@v2
+        with:
+          tool: nextest
+
       - name: Build
         run: cargo +${{ matrix.rust }} build
 
+      - name: Test
+        run: cargo +${{ matrix.rust }} nextest run --workspace
+
       - name: Test docs
         run: cargo +${{ matrix.rust }} test
 

Cargo.toml

@@ -24,10 +24,13 @@ grass = "0.13"
 lightningcss = "1.0.0-alpha.68"
 proc-macro2 = "1"
 quote = "1"
+regex = "1.12.3"
 serde = "1"
 serde_yml = "0.0.12"
+semver = "1.0.27"
 syn = "2"
 syntect = "5"
+thiserror = "2.0.18"
 
 [features]
 nightly = ["cot-site-macros/nightly"]

cot-site-common/Cargo.toml

@@ -6,3 +6,5 @@ edition = "2024"
 [dependencies]
 comrak.workspace = true
 serde.workspace = true
+semver.workspace = true
+thiserror.workspace = true

cot-site-common/src/lib.rs

@@ -1 +1,7 @@
 pub mod md_pages;
+mod utils;
+pub use utils::{Version, VersionError};
+
+pub const MASTER_VERSION: &str = "master";
+pub const LATEST_VERSION: &str = "v0.5";
+pub const ALL_VERSIONS: &[&str] = &[MASTER_VERSION, "v0.5", "v0.4", "v0.3", "v0.2", "v0.1"];

cot-site-common/src/utils.rs

@@ -0,0 +1,127 @@
+use std::fmt::Display;
+use std::str::FromStr;
+
+use semver::Version as SemverVersion;
+use thiserror::Error;
+
+use crate::{LATEST_VERSION, MASTER_VERSION};
+
+/// Errors related to version parsing and handling.
+#[derive(Debug, Error)]
+pub enum VersionError {
+    /// Error parsing version string.
+    #[error("invalid version string: {0}")]
+    InvalidVersion(#[from] semver::Error),
+}
+
+/// A semver version type.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Version(SemverVersion);
+
+impl Version {
+    /// Creates a new version from major, minor, and patch numbers.
+    ///
+    /// # Example
+    /// ```
+    /// let v = Version::new(0, 5, 0);
+    /// assert_eq!(v.to_string(), "0.5.0");
+    /// ```
+    pub fn new(major: u64, minor: u64, patch: u64) -> Self {
+        Version(SemverVersion::new(major, minor, patch))
+    }
+
+    /// Returns the major version number.
+    ///
+    /// # Example
+    /// ```
+    /// let v = Version::new(0, 5, 0);
+    /// assert_eq!(v.major(), 0);
+    /// ```
+    pub fn major(&self) -> u64 {
+        self.0.major
+    }
+
+    /// Returns the minor version number.
+    ///
+    /// # Example
+    /// ```
+    /// let v = Version::new(0, 5, 0);
+    /// assert_eq!(v.minor(), 5);
+    /// ```
+    pub fn minor(&self) -> u64 {
+        self.0.minor
+    }
+
+    /// Returns the patch version number.
+    ///
+    /// # Example
+    /// ```
+    /// let v = Version::new(0, 5, 0);
+    /// assert_eq!(v.patch(), 0);
+    /// ```
+    pub fn patch(&self) -> u64 {
+        self.0.patch
+    }
+}
+
+impl Display for Version {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0.to_string())
+    }
+}
+
+impl FromStr for Version {
+    type Err = VersionError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        // replace "master" with latest version
+        let s = if s == MASTER_VERSION || s == "" {
+            LATEST_VERSION
+        } else {
+            s
+        };
+
+        // canonicalize version string by adding ".0" for missing minor/patch
+        let s = canonicalize_version_string(s);
+
+        let semver_version = SemverVersion::parse(s.as_str())?;
+        Ok(Version(semver_version))
+    }
+}
+
+fn canonicalize_version_string(s: &str) -> String {
+    let s = s.trim_start_matches('v');
+    let parts: Vec<&str> = s.split('.').collect();
+    match parts.len() {
+        1 => format!("{}.0.0", parts[0]),
+        2 => format!("{}.{}.0", parts[0], parts[1]),
+        _ => s.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn test_version_parsing() {
+        let v = Version::from_str("v0.5").unwrap();
+        assert_eq!(v.to_string(), "0.5.0");
+
+        let v = Version::from_str("0.5").unwrap();
+        assert_eq!(v.to_string(), "0.5.0");
+
+        let v = Version::from_str("master").unwrap();
+        assert_eq!(v.to_string(), canonicalize_version_string(LATEST_VERSION));
+
+        let v = Version::from_str("").unwrap();
+        assert_eq!(v.to_string(), canonicalize_version_string(LATEST_VERSION));
+    }
+
+    #[test]
+    fn test_canonicalize_version_string() {
+        assert_eq!(canonicalize_version_string("v0.5"), "0.5.0");
+        assert_eq!(canonicalize_version_string("0.5"), "0.5.0");
+        assert_eq!(canonicalize_version_string("v0.5.1"), "0.5.1");
+        assert_eq!(canonicalize_version_string("0.5.1"), "0.5.1");
+    }
+}

cot-site-macros/Cargo.toml

@@ -17,6 +17,7 @@ quote.workspace = true
 serde_yml.workspace = true
 syn.workspace = true
 syntect = { workspace = true, features = ["dump-load"] }
+regex = { workspace = true, features = ["default"] }
 
 [build-dependencies]
 syntect = { workspace = true, features = ["dump-create"] }

cot-site-macros/src/lib.rs

@@ -3,9 +3,7 @@
 use proc_macro::TokenStream;
 
 use crate::md_pages::MdPageInput;
-
 mod md_pages;
-
 #[proc_macro]
 pub fn md_page(input: TokenStream) -> TokenStream {
     let input = proc_macro2::TokenStream::from(input);

cot-site-macros/src/md_pages.rs

@@ -1,8 +1,10 @@
 mod rendering;
 
 use std::path::Path;
+use std::str::FromStr;
 use std::sync::Mutex;
 
+use cot_site_common::Version;
 use cot_site_common::md_pages::{FrontMatter, MdPage, MdPageHeadingAdapter, Section};
 use proc_macro2::TokenStream;
 use quote::quote;
@@ -119,7 +121,8 @@ pub(super) fn parse_md_page(prefix: &str, link: &str) -> MdPage {
         .render(render_plugins)
         .build();
 
-    let md_page_content = markdown_to_html(&md_page_content, &options, &plugins);
+    let version = Version::from_str(prefix).expect("invalid version in md page prefix");
+    let md_page_content = markdown_to_html(&md_page_content, &options, &plugins, version);
     let sections = heading_adapter.sections.lock().unwrap().clone();
     let root_section = fix_section_children(&sections);