docs: add mdBook documentation site with FG branding

.cargo/config.toml

@@ -4,4 +4,9 @@ ci-fmt = "fmt --all -- --check"
 ci-lint = "clippy --workspace --all-targets --features compare,simulate,profile-adjacency -- -D warnings -W clippy::pedantic"
 # Run tests with test-utils feature enabled (allows binary tests to use library test utilities)
 t = "test --features test-utils"
+# Generate and serve documentation locally (runs xtask then mdbook serve)
+docs = "run --package xtask -- docs"
+# Generate and build documentation (for CI validation)
+docs-build = "run --package xtask -- docs-build"
+
 [build]

.gitignore

@@ -34,3 +34,9 @@ Session.vim
 # Local notes (DEV.md, RD.md)
 /notes/
 /plans/
+
+# mdBook auto-generated output and content
+docs/book/
+docs/src/SUMMARY.md
+docs/src/tools/
+docs/src/metrics/

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    rust: "latest"  # RTD does not support specific 1.x versions; rust-toolchain.toml pins the actual version
+  commands:
+    # Install mdbook
+    - cargo install mdbook --version 0.5.2
+
+    # Generate documentation markdown and build the mdbook site
+    - cargo run --package xtask --release -- docs-build
+
+    # Move output to where Read the Docs expects it
+    - mkdir -p _readthedocs/html
+    - cp -r docs/book/. _readthedocs/html/

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "crates/fgumi-raw-bam", "crates/fgumi-dna", "crates/fgumi-bgzf", "crates/fgumi-metrics", "crates/fgumi-sam", "crates/fgumi-simd-fastq", "crates/fgumi-umi", "crates/fgumi-consensus"]
+members = [".", "crates/fgumi-raw-bam", "crates/fgumi-dna", "crates/fgumi-bgzf", "crates/fgumi-metrics", "crates/fgumi-sam", "crates/fgumi-simd-fastq", "crates/fgumi-umi", "crates/fgumi-consensus", "crates/xtask"]
 resolver = "2"
 
 [workspace.package]
@@ -66,7 +66,7 @@ memchr = "2"
 murmur3 = "0.5"
 statrs = "0.18"
 bytesize = "2.3"
-sysinfo = { version = "0.38", default-features = false, features = ["system"] }
+sysinfo = { version = "0.38", default-features = false, features = ["system"] } # unconditionally used by validate_against_system_memory
 rayon = "1.10"
 approx = "0.5.1"
 ahash = "0.8"

crates/xtask/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "xtask"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+description = "Build tasks for fgumi (doc generation, etc.)"
+repository.workspace = true
+license.workspace = true
+publish = false
+
+[features]
+# Mirror the compare feature from the fgumi crate to include the compare tool in docs
+compare = ["fgumi/compare"]
+# Mirror the simulate feature from the fgumi crate to include simulate tools in docs
+simulate = ["fgumi/simulate"]
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4", features = ["derive"] }
+syn = { version = "2", features = ["full", "extra-traits"] }
+quote = "1"
+fgumi = { path = "../.." }
+
+[lints.clippy]
+pedantic = { level = "deny", priority = -1 }
+# Relaxations for build tool code (heavy string formatting)
+format_push_string = "allow"
+single_char_add_str = "allow"

crates/xtask/src/generate_docs.rs

@@ -0,0 +1,28 @@
+use anyhow::Result;
+use std::path::Path;
+
+use crate::generate_metrics;
+use crate::generate_summary;
+use crate::generate_tools;
+
+/// Generate all documentation markdown files.
+///
+/// Creates auto-generated tool reference pages, metric reference pages, and the
+/// SUMMARY.md table of contents in the mdBook source directory.
+pub fn generate() -> Result<()> {
+    let docs_src = Path::new("docs/src");
+
+    // Generate tool reference pages
+    let tool_pages = generate_tools::generate(docs_src)?;
+    eprintln!("Generated {} tool pages", tool_pages.len());
+
+    // Generate metric reference pages
+    let metric_pages = generate_metrics::generate(docs_src)?;
+    eprintln!("Generated {} metric pages", metric_pages.len());
+
+    // Generate SUMMARY.md
+    generate_summary::generate(docs_src, &tool_pages, &metric_pages)?;
+    eprintln!("Generated SUMMARY.md");
+
+    Ok(())
+}