Digine-Labs · ermvrs · Mar 5, 2026 · Mar 4, 2026
diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
@@ -29,6 +29,8 @@ jobs:
       MDBOOK_VERSION: 0.4.36
     steps:
       - uses: actions/checkout@v4
+      - name: Install scarb
+        uses: software-mansion/setup-scarb@v1.3.2
       - name: Install mdBook
         run: |
           curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
@@ -37,12 +39,12 @@ jobs:
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
-      - name: Build with mdBook
-        run: mdbook build docs/website
+      - name: Generate docs
+        run: bash scripts/generate_doc.sh
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/website/book
+          path: target/doc/book
 
   # Deployment job
   deploy:

diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,24 @@
+[book]
+authors = ["Alexandria contributors"]
+language = "en"
+src = "src"
+title = "Alexandria - Cairo Standard Library"
+description = "Alexandria is a community maintained standard library for Cairo. A collection of useful algorithms and data structures."
+
+[build]
+create-missing = false
+
+[output.html]
+git-repository-url = "https://github.com/keep-starknet-strange/alexandria"
+edit-url-template = "https://github.com/keep-starknet-strange/alexandria/edit/main/{path}"
+no-section-label = false
+
+[output.html.playground]
+runnable = false
+
+[output.html.fold]
+enable = true
+level = 2
+
+[output.html.code.hidelines]
+cairo = "# "
diff --git a/docs/intro.md b/docs/intro.md
@@ -0,0 +1,59 @@
+# Alexandria Library Documentation
+
+## About
+
+Alexandria is a community maintained standard library for Cairo.
+It is a collection of useful algorithms and data structures implemented in Cairo.
+
+## Version
+
+Current version is **0.10.0** compatible with Cairo **2.16.0**
+
+## Packages
+
+- [ASCII](./alexandria_ascii.md)
+- [Bitcoin](./alexandria_btc.md)
+- [Bytes](./alexandria_bytes.md)
+- [Data Structures](./alexandria_data_structures.md)
+- [Encoding](./alexandria_encoding.md)
+- [EVM](./alexandria_evm.md)
+- [JSON](./alexandria_json.md)
+- [Linalg](./alexandria_linalg.md)
+- [Math](./alexandria_math.md)
+- [Merkle Tree](./alexandria_merkle_tree.md)
+- [Numeric](./alexandria_numeric.md)
+- [Searching](./alexandria_searching.md)
+- [Sorting](./alexandria_sorting.md)
+- [Storage](./alexandria_storage.md)
+- [Utils](./alexandria_utils.md)
+
+## Installation
+
+```bash
+scarb add alexandria_ascii@0.10.0
+scarb add alexandria_btc@0.10.0
+scarb add alexandria_bytes@0.10.0
+scarb add alexandria_data_structures@0.10.0
+scarb add alexandria_encoding@0.10.0
+scarb add alexandria_evm@0.10.0
+scarb add alexandria_json@0.10.0
+scarb add alexandria_linalg@0.10.0
+scarb add alexandria_math@0.10.0
+scarb add alexandria_merkle_tree@0.10.0
+scarb add alexandria_numeric@0.10.0
+scarb add alexandria_searching@0.10.0
+scarb add alexandria_sorting@0.10.0
+scarb add alexandria_storage@0.10.0
+scarb add alexandria_utils@0.10.0
+```
+
+## Prerequisites
+
+- [Cairo](https://github.com/starkware-libs/cairo)
+- [Scarb](https://docs.swmansion.com/scarb)
+
+## Links
+
+- [GitHub Repository](https://github.com/keep-starknet-strange/alexandria)
+- [Report a Bug](https://github.com/keep-starknet-strange/alexandria/issues/new?assignees=&labels=bug&template=01_BUG_REPORT.md&title=bug%3A+)
+- [Request a Feature](https://github.com/keep-starknet-strange/alexandria/issues/new?assignees=&labels=enhancement&template=02_FEATURE_REQUEST.md&title=feat%3A+)
diff --git a/packages/ascii/src/lib.cairo b/packages/ascii/src/lib.cairo
@@ -1,2 +1,6 @@
+//! # Alexandria ASCII
+//!
+//! Utilities for converting numeric types to ASCII representations.
+
 pub mod integer;
 pub use integer::{ToAsciiArrayTrait, ToAsciiTrait};
diff --git a/packages/btc/src/lib.cairo b/packages/btc/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria BTC
+//!
+//! Bitcoin utilities for Cairo, including address generation, BIP-322/340 signature
+//! verification, transaction encoding/decoding, and key management.
+
 pub mod address;
 pub mod bip322;
 pub mod bip340;

diff --git a/packages/bytes/src/lib.cairo b/packages/bytes/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Bytes
+//!
+//! Byte manipulation utilities for Cairo, including a `Bytes` type (similar to Solidity bytes),
+//! bit arrays, byte readers, and byte array extensions.
+
 pub mod bit_array;
 pub mod byte_appender;
 pub mod byte_array_ext;

diff --git a/packages/data_structures/src/lib.cairo b/packages/data_structures/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Data Structures
+//!
+//! Common data structures for Cairo, including queues, stacks, vectors,
+//! and array/span extensions.
+
 pub mod array_ext;
 
 pub mod bit_array;

diff --git a/packages/encoding/src/lib.cairo b/packages/encoding/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Encoding
+//!
+//! Encoding and decoding utilities for Cairo, including Base58, Base64, Bech32, RLP,
+//! and Solidity ABI encoding.
+
 pub mod base58;
 pub mod base64;
 pub mod bech32;

diff --git a/packages/evm/src/lib.cairo b/packages/evm/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria EVM
+//!
+//! EVM compatibility utilities for Cairo, including ABI encoding/decoding,
+//! function selectors, and signature verification.
+
 pub mod constants;
 pub mod decoder;
 pub mod encoder;

diff --git a/packages/json/src/lib.cairo b/packages/json/src/lib.cairo
@@ -1,2 +1,6 @@
+//! # Alexandria JSON
+//!
+//! JSON parsing and serialization for Cairo.
+
 pub mod json;
 
diff --git a/packages/linalg/src/lib.cairo b/packages/linalg/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Linear Algebra
+//!
+//! Linear algebra utilities for Cairo, including dot product, Kronecker product,
+//! and vector norms.
+
 pub mod dot;
 pub mod kron;
 pub mod norm;

diff --git a/packages/math/src/lib.cairo b/packages/math/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Math
+//!
+//! A collection of math libraries and algorithms for Cairo, including modular arithmetic,
+//! cryptographic primitives (Ed25519, BIP-340), number theory, trigonometry, and fixed-point math.
+
 pub mod aliquot_sum;
 pub mod armstrong_number;
 

diff --git a/packages/merkle_tree/src/lib.cairo b/packages/merkle_tree/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Merkle Tree
+//!
+//! Merkle tree implementations for Cairo, including Pedersen and Poseidon hashers,
+//! and storage proofs.
+
 pub mod merkle_tree;
 pub mod storage_proof;
 use storage_proof::BinaryNodeImpl;
diff --git a/packages/numeric/src/lib.cairo b/packages/numeric/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Numeric
+//!
+//! Numerical analysis utilities for Cairo, including interpolation, cumulative sum/product,
+//! differentiation, and trapezoidal integration.
+
 pub mod cumprod;
 pub mod cumsum;
 pub mod diff;

diff --git a/packages/searching/src/lib.cairo b/packages/searching/src/lib.cairo
@@ -1,3 +1,8 @@
+//! # Alexandria Searching
+//!
+//! Search algorithms for Cairo, including binary search, Boyer-Moore string matching,
+//! Dijkstra's shortest path, and Levenshtein distance.
+
 pub mod binary_search;
 pub mod bm_search;
 pub mod dijkstra;

diff --git a/packages/sorting/src/lib.cairo b/packages/sorting/src/lib.cairo
@@ -1,3 +1,7 @@
+//! # Alexandria Sorting
+//!
+//! Sorting algorithms for Cairo, including bubble sort, merge sort, and quick sort.
+
 mod bubble_sort;
 pub mod interface;
 pub mod merge_sort;

diff --git a/packages/storage/src/lib.cairo b/packages/storage/src/lib.cairo
@@ -1,3 +1,7 @@
+//! # Alexandria Storage
+//!
+//! Starknet storage utilities, including a growable `List` type for contract storage.
+
 pub mod list;
 
 

diff --git a/packages/utils/src/lib.cairo b/packages/utils/src/lib.cairo
@@ -1 +1,5 @@
+//! # Alexandria Utils
+//!
+//! General utilities for Cairo, including `Display` and `Debug` formatting for Starknet types.
+
 pub mod fmt;
diff --git a/scripts/generate_doc.sh b/scripts/generate_doc.sh
@@ -1,114 +1,41 @@
 #!/bin/bash
 
-#######################################
-##to be executed in scripts folder#####
-#######################################
+set -e
 
-set -e  # Exit immediately if a command exits with a non-zero status
-
-# Get the script directory and project root
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$SCRIPT_DIR/.."
-SCARB_TOML="$PROJECT_ROOT/Scarb.toml"
-BACKUP_TOML="$PROJECT_ROOT/Scarb.toml.bak"
-
-# Backup the original Scarb.toml
-cp "$SCARB_TOML" "$BACKUP_TOML"
-
-# Remove the "packages/macros" line from the workspace members
-awk '
-  BEGIN { skip=0 }
-  /^\[workspace\]/ { in_workspace=1 }
-  in_workspace && /^\[/ && !/^\[workspace\]/ { in_workspace=0 }
-  in_workspace && /"packages\/macros"/ { next }
-  { print }
-' "$BACKUP_TOML" > "$SCARB_TOML"
 
-# Run scarb doc from project root
 cd "$PROJECT_ROOT"
-scarb doc
-
-# Restore original Scarb.toml
-mv "$BACKUP_TOML" "$SCARB_TOML"
-
-echo "✅ Documentation generated"
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$SCRIPT_DIR"
-DOC_ROOT="$PROJECT_ROOT/target/doc"
-SUMMARY_BOOK="$PROJECT_ROOT/book"
-SUMMARY_SRC="$SUMMARY_BOOK/src"
-SUMMARY_MD="$SUMMARY_SRC/SUMMARY.md"
 
-echo "🛠️ Generating unified Alexandria docs..."
+REMOTE_URL="https://github.com/keep-starknet-strange/alexandria/"
+DOC_SRC="target/doc/src"
 
-rm -rf "$SUMMARY_BOOK"
-mkdir -p "$SUMMARY_SRC"
+# Generate markdown docs (without --build so we can customize before building)
+scarb doc --workspace \
+  --exclude alexandria_macros \
+  --exclude alexandria_macros_tests \
+  --remote-base-url "$REMOTE_URL"
 
-# Initialize mdBook if needed
-if [ ! -f "$SUMMARY_BOOK/book.toml" ]; then
-    mdbook init --force book
-    echo "[output.html.fold]" >> "$SUMMARY_BOOK/book.toml"
-    echo "enable = true    # whether or not to enable section folding" >> "$SUMMARY_BOOK/book.toml"
-    echo "level = 0         # the depth to start folding" >> "$SUMMARY_BOOK/book.toml"
-    cd "$PROJECT_ROOT"
+# Detect sed in-place flag (macOS vs Linux)
+if sed --version >/dev/null 2>&1; then
+  SED_INPLACE=(sed -i)
+else
+  SED_INPLACE=(sed -i '')
 fi
 
-echo "# Alexandria Standard Library" > "$SUMMARY_MD"
-echo "" >> "$SUMMARY_MD"
-
-for pkg_dir in "$PROJECT_ROOT"/packages/*; do
-    [ -d "$pkg_dir" ] || continue
-    pkg_name=$(basename "$pkg_dir")
-
-    #skip macro package
-    if [ "$pkg_name" = "macros" ]; then
-        echo "⏭️ Skipping macros"
-        continue
-    fi
-
-    echo "📦 Processing $pkg_name..."
-    SRC_DIR="$DOC_ROOT/alexandria_$pkg_name/src"
-    DEST_DIR="$SUMMARY_SRC/$pkg_name"
-    PKG_SUMMARY="$SRC_DIR/SUMMARY.md"
-
-    if [ -d "$SRC_DIR" ]; then
-        mkdir -p "$DEST_DIR"
-        cp "$SRC_DIR"/*.md "$DEST_DIR/"
-
-        echo "" >> "$SUMMARY_MD"
-        echo "## $pkg_name" >> "$SUMMARY_MD"
-        # Add main link to sub-summary
-        echo "- [$pkg_name]($pkg_name/SUMMARY.md)" >> "$SUMMARY_MD"
-        if [ -f "$PKG_SUMMARY" ]; then
-            while IFS= read -r line; do
-
-              # Skip the "# Summary" line
-                if [[ "$line" == "# Summary" ]]; then
-                    continue
-                fi
+# Inject custom intro page
+cp docs/intro.md "$DOC_SRC/intro.md"
+"${SED_INPLACE[@]}" '1i\
+[Introduction](./intro.md)
+' "$DOC_SRC/SUMMARY.md"
 
-                # Replace ./ with package-prefixed paths
-                if [[ "$line" =~ \[.*\]\(\.\/(.*)\) ]]; then
-                    line=$(echo "$line" | sed -E "s|\(\.\/|\($pkg_name/|g")
-                fi
+# Remove core crate section (Cairo built-in, not excludable via --exclude)
+"${SED_INPLACE[@]}" '/^- \[core\]/,/^- \[/{/^- \[core\]/d;/^- \[/!d;}' "$DOC_SRC/SUMMARY.md"
 
-                 # Add 4-space indentation unless it's an empty line
-                if [[ -n "$line" ]]; then
-                    echo "    $line" >> "$SUMMARY_MD"
-                else
-                    echo "" >> "$SUMMARY_MD"
-                fi
+# Use our custom book.toml
+cp docs/book.toml target/doc/book.toml
 
-            done < "$PKG_SUMMARY"
-        else
-            echo "⚠️ No SUMMARY.md found for $pkg_name"
-        fi
-    else
-        echo "⚠️ No docs found for $pkg_name"
-    fi
-done
+# Build mdBook
+mdbook build target/doc
 
-cd "$SUMMARY_BOOK"
-mdbook build
-echo "Open $SUMMARY_BOOK/book/index.html to see generated documentation"
+echo "Documentation generated at target/doc/book/index.html"