Update readme

README.md

@@ -1,8 +1,8 @@
 # Install dependencies
 
-We use `pixi` for Python, and `cargo` for Rust.
+We use `pixi` as a dependency manager for Python, and `cargo` for Rust.
 
-Install `pixi` by following https://pixi.sh/latest/  -- it should be something along the lines of:
+Install `pixi` by following https://pixi.sh/latest/ -- it should be something along the lines of:
 
 ```bash
 curl -fsSL https://pixi.sh/install.sh | bash
@@ -14,61 +14,68 @@ Install `cargo` by following https://rustup.rs/ -- it should be something along
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-# Running tests
-
-Cargo tests
-
-```bash
-cargo test
-```
-
-Pytest
-
-```bash
-pixi run pytest
-```
-
-# Build whitepaper
-
-Whitepaper is still built with buck2.
-This may change since buck2 is a lot of work to maintain in contrast with plain cargo.
-
-```bash
-buck2 build //docs/whitepaper:whitepaper
-```
-
-The generated pdf can be found by running
+To run end-to-end tests, we use [cargo-make](https://github.com/sagiegurari/cargo-make), which you can install by running
 
 ```bash
-buck2 targets --show-output //docs/whitepaper:whitepaper 2>/dev/null | grep out/whitepaper.pdf | awk '{print $2}'
+cargo install --force cargo-make
 ```
 
 # Usage
 
 ## Key generation
 
-### Option 1: key generation with the `dc` cli tool:
+### Option 1 (recommended): key generation with the `dc` cli tool:
 
 For node provider:
+
 ```bash
 cargo run --bin dc -- keygen --generate --identity np
 ```
 
 For user:
+
 ```bash
 cargo run --bin dc -- keygen --generate --identity user
 ```
 
-### Option 2: key generation with openssl:
+### Option 2 (alternative): key generation with openssl:
 
 For node provider:
+
 ```bash
 mkdir -p $HOME/.dcc/identities/np
 openssl genpkey -algorithm ED25519 -out $HOME/.dcc/identities/np/private.pem
 ```
 
 For user:
+
 ```bash
 mkdir -p $HOME/.dcc/identities/user
 openssl genpkey -algorithm ED25519 -out $HOME/.dcc/identities/user/private.pem
 ```
+
+# Running tests
+
+You can run unit tests with:
+
+```bash
+cargo test
+```
+
+Or you can run the complete suite of unit tests and the canister tests with PocketIC, with:
+
+```bash
+cargo make
+```
+
+# Build whitepaper
+
+There is a Python build script that uses a docker images with latex and mermaid.js to build the whitepaper PDF.
+
+You can invoke the build script with:
+
+```bash
+pixi run python3 ./docs/whitepaper/build.py
+```
+
+The result PDF document will be at `build/docs/whitepaper/whitepaper.pdf`.