Documentation Cleanup and Rustdoc Deployment Improvements

.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

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)

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/)

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:

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"

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.