Skip to content

Documentation Cleanup and Rustdoc Deployment Improvements #2129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/workflows/bench.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
34 changes: 3 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
4 changes: 3 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
@@ -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/)
Expand Down
2 changes: 2 additions & 0 deletions docs/vm/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions vm/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
21 changes: 20 additions & 1 deletion vm/src/lib.rs
Original file line number Diff line number Diff line change
@@ -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.
Expand Down