From e8bd1f7f494097c8b0dd657f5274a7aa36fe32e1 Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:04:41 +0300 Subject: [PATCH 1/6] docs: Add module-level rustdoc with links to README and docs, mention mermaid support --- vm/src/lib.rs | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/vm/src/lib.rs b/vm/src/lib.rs index 425a5796fd..e6770d3f90 100644 --- a/vm/src/lib.rs +++ b/vm/src/lib.rs @@ -1,4 +1,23 @@ -//! # An implementation of the Cairo virtual machine +//! # Cairo VM +//! +//! This crate provides a fast and safe implementation of the Cairo virtual machine in Rust. +//! +//! - [Project README](https://github.com/lambdaclass/cairo-vm/blob/main/README.md) +//! - [Extended documentation](https://github.com/lambdaclass/cairo-vm/blob/main/docs/README.md) +//! +//! ## Features +//! - STARK-friendly execution trace +//! - Custom hint processor support +//! - Tracing and debugging tools +//! +//! ## Example +//! ```rust +//! use cairo_vm::vm::vm_core::VirtualMachine; +//! // ... usage example ... +//! ``` +//! +//! ## Diagrams +//! Mermaid diagrams are supported in rustdoc via the `aquamarine` dependency. //! //! ## Feature Flags //! - `std`: Enables usage of the [`std`] standard library. Enabled by default. From 8617b85b25acfcca8e5d53830b53142104ddb312 Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:05:48 +0300 Subject: [PATCH 2/6] docs: Add cross-references to main README and docs index in VM documentation --- docs/vm/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/vm/README.md b/docs/vm/README.md index f340a4b8c2..f4d3bbf853 100644 --- a/docs/vm/README.md +++ b/docs/vm/README.md @@ -2,6 +2,8 @@ # How does the Cairo VM work? +> For a general overview, see the [main README](../../README.md). For the documentation structure, see [docs/README.md](../README.md). + ## High Level Overview The Cairo virtual machine is meant to be used in the context of STARK validity proofs. What this means is that the point of Cairo is not just to execute some code and get a result, but to *prove* to someone else that said execution was done correctly, without them having to re-execute the entire thing. The rough flow for it looks like this: From f81d9510295567ad716d73ef07afb8d27f3c8a43 Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:06:39 +0300 Subject: [PATCH 3/6] docs: Add links to benchmark results and extended documentation --- README.md | 34 +++------------------------------- 1 file changed, 3 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index d701bad50a..b78c366543 100644 --- a/README.md +++ b/README.md @@ -298,37 +298,7 @@ Cairo-vm offers a tracer which gives you a visualization of how your memory and ## 📊 Benchmarks -Running a [Cairo program](./cairo_programs/benchmarks/big_fibonacci.cairo) that gets the 1.5 millionth Fibonacci number we got the following benchmarks: - -- Execution time with [Criterion](./docs/benchmarks/criterion_benchmark.pdf) -- [Flamegraph](./docs/benchmarks/flamegraph.svg) -- Github action [results](https://lambdaclass.github.io/cairo-vm/) - -Note before running the benchmark suite: the benchmark named [iai_benchmark](https://github.com/lambdaclass/cairo-vm/blob/8dba86dbec935fa04a255e2edf3d5d184950fa22/Cargo.toml#L59) depends on Valgrind. Please make sure it is installed prior to running the `iai_benchmark` benchmark. - -Run the complete benchmark suite with cargo: - -```bash -cargo bench -``` - -Run only the `criterion_benchmark` benchmark suite with cargo: - -```bash -cargo bench --bench criterion_benchmark -``` - -Run only the `iai_benchmark` benchmark suite with cargo: - -```bash -cargo bench --bench iai_benchmark -``` - -Benchmark the `cairo-vm` in a hyper-threaded environment with the [`examples/hyper_threading/ crate`](examples/hyper_threading/) -```bash -make hyper-threading-benchmarks -``` - +Benchmark results are available in [docs/benchmarks/criterion_benchmark.pdf](docs/benchmarks/criterion_benchmark.pdf) and [docs/benchmarks/flamegraph.svg](docs/benchmarks/flamegraph.svg). ## 📜 Changelog @@ -357,6 +327,8 @@ You can find more detailed instructions in the [CONTRIBUTING.md](CONTRIBUTING.md ## 📚 Documentation +See [docs/README.md](docs/README.md) for extended documentation, including architecture, usage, and developer guides. + ### Cairo - From Cairo Documentation: [How Cairo Works](https://docs.cairo-lang.org/how_cairo_works/index.html) From 2774a22ca11b42cafeaf897ca089c31e25034e6e Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:07:22 +0300 Subject: [PATCH 4/6] docs: Improve docs index, add cross-links and benchmark results references --- docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c781d4d706..af8f3e8325 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,10 @@ # Documentation +This folder contains extended documentation for Cairo VM. For a general overview, see the [main README](../README.md). + * [How does the Cairo VM work?](./vm/) * [How does the original Cairo VM work?](./python_vm/) -* [Benchmarks](./benchmarks/) +* [Benchmarks](./benchmarks/) ([see results](./benchmarks/criterion_benchmark.pdf), [flamegraph](./benchmarks/flamegraph.svg)) * [Custom Hint Processor](./hint_processor/) * [How to run a cairo program with custom hints](./hint_processor/builtin_hint_processor) * [References parsing](./references_parsing/) From e77a113626048594e6c4375583037b55996db196 Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:07:58 +0300 Subject: [PATCH 5/6] chore: Add aquamarine as dev-dependency for mermaid diagrams in rustdoc --- vm/Cargo.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/vm/Cargo.toml b/vm/Cargo.toml index bba3eab4ba..b0b9a34cc7 100644 --- a/vm/Cargo.toml +++ b/vm/Cargo.toml @@ -82,6 +82,7 @@ clap = { version = "4.3.10", features = ["derive"], optional = true} assert_matches = "1.5.0" rstest = { version = "0.17.0", default-features = false } num-prime = { version = "0.4.3", features = ["big-int"] } +aquamarine = "0.7" [target.'cfg(target_arch = "wasm32")'.dev-dependencies] wasm-bindgen-test = "0.3.50" From 8bf5cdd9db4f29051abad80bfc2ef41b7d3b92e8 Mon Sep 17 00:00:00 2001 From: MozirDmitriy Date: Tue, 24 Jun 2025 22:08:24 +0300 Subject: [PATCH 6/6] ci: Add rustdoc build and deploy to GitHub Pages in benchmark workflow --- .github/workflows/bench.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml index f30934c803..9572e6a7f2 100644 --- a/.github/workflows/bench.yml +++ b/.github/workflows/bench.yml @@ -45,3 +45,13 @@ jobs: alert-comment-cc-users: '@unbalancedparentheses' - name: Clean benches run: make clean + + - name: Build rustdoc + run: cargo doc --no-deps --workspace + + - name: Deploy rustdoc to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./target/doc + destination_dir: docs