Add mdBook documentation site

- Add docs/ directory with mdBook configuration
- Include INTEGRATION_GUIDE.md, BENCHMARKING.md as book chapters
- Add documentation modules to lib.rs for docs.rs
- Update GitHub Actions to build mdBook + rustdoc

Signed-off-by: Zvi Schneider <z2357@outlook.com>

Author: zvi-code

.github/workflows/docs.yml

@@ -22,17 +22,33 @@ jobs:
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
+      
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
 
-      - name: Build docs
+      - name: Build rustdoc
         run: cargo doc --no-deps --document-private-items
-        
-      - name: Add redirect
-        run: echo '<meta http-equiv="refresh" content="0;url=keyspace_tracker/index.html">' > target/doc/index.html
+      
+      - name: Build mdBook
+        run: mdbook build docs
+      
+      - name: Merge documentation
+        run: |
+          # Use mdBook as the main site
+          mkdir -p target/site
+          cp -r target/book/* target/site/
+          # Add rustdoc under /api/
+          mkdir -p target/site/api
+          cp -r target/doc/* target/site/api/
+          # Add redirect for API docs
+          echo '<meta http-equiv="refresh" content="0;url=keyspace_tracker/index.html">' > target/site/api/index.html
         
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: target/doc
+          path: target/site
 
   deploy:
     needs: build

docs/book.toml

@@ -0,0 +1,12 @@
+[book]
+title = "keyspace_tracker"
+authors = ["Zvi Schneider"]
+description = "High-performance bitmap-based existence tracking"
+src = "src"
+
+[build]
+build-dir = "../target/book"
+
+[output.html]
+git-repository-url = "https://github.com/zvi-code/keyspace_tracker"
+edit-url-template = "https://github.com/zvi-code/keyspace_tracker/edit/mainline/docs/{path}"

docs/src/README.md

@@ -0,0 +1,3 @@
+# keyspace_tracker
+
+{{#include ../../README.md}}

docs/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+[Introduction](./README.md)
+
+# User Guide
+
+- [Integration Guide](./integration-guide.md)
+- [Benchmarking](./benchmarking.md)
+
+# Reference
+
+- [API Documentation](../api/keyspace_tracker/index.html)
+- [Specification](./spec.md)

docs/src/benchmarking.md

@@ -0,0 +1 @@
+{{#include ../../BENCHMARKING.md}}

docs/src/integration-guide.md

@@ -0,0 +1 @@
+{{#include ../../INTEGRATION_GUIDE.md}}

docs/src/spec.md

@@ -0,0 +1 @@
+{{#include ../../prefix_tracker_spec.md}}

src/lib.rs

@@ -211,6 +211,26 @@ pub use iterators::{
 };
 pub use tracker::PrefixTracker;
 
+// =============================================================================
+// Documentation Modules
+// =============================================================================
+
+/// Integration guide for keyspace_tracker.
+///
+/// This module contains the full integration specification for using
+/// keyspace_tracker with database benchmarking tools.
+#[cfg(doc)]
+#[doc = include_str!("../INTEGRATION_GUIDE.md")]
+pub mod integration_guide {}
+
+/// Benchmarking guide for keyspace_tracker.
+///
+/// This module contains performance tuning and benchmarking guidance
+/// for achieving maximum performance on various platforms.
+#[cfg(doc)]
+#[doc = include_str!("../BENCHMARKING.md")]
+pub mod benchmarking {}
+
 use std::sync::Arc;
 
 use ahash::RandomState as AHasher;