diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml index cb8e02f4..900fcb01 100644 --- 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 new file mode 100644 index 00000000..785b26f3 --- /dev/null +++ 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 new file mode 100644 index 00000000..699abcde --- /dev/null +++ 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 index cb07ee4b..882444f0 100644 --- 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 index 37a15d14..bbb6a369 100644 --- 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 index 11223e8d..de91557e 100644 --- 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 index 9c461a16..04234cb7 100644 --- 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 index 31459cd9..987a6fcb 100644 --- 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 index 9b22518e..efc5ea25 100644 --- 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 index f9920421..520b2bf6 100644 --- 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 index 91cbc945..759d69cd 100644 --- 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 index 39d2b46f..12201685 100644 --- 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 index 21c1e456..38e218b5 100644 --- 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 index c96667be..d482cc22 100644 --- 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 index 4b24a87f..2d4e2b19 100644 --- 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 index 5affd832..e7d71af2 100644 --- 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 index e7e977c9..98cbaef6 100644 --- 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 index 4294b191..9af67c41 100644 --- 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 index 2e9a7990..41bb4cd8 100755 --- 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" \ No newline at end of file +echo "Documentation generated at target/doc/book/index.html"