Merge pull request #812 from primitivefinance/documentation-additions

Documentation additions

.github/workflows/book.yaml

@@ -12,73 +12,69 @@ on:
   merge_group:
 
 jobs:
-  test:
+  build:
     runs-on: ubuntu-latest
-    name: test
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      # Install Rust
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
 
+      # Install mdbook
       - name: Install mdbook
-        run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
+        run: cargo install mdbook --vers "^0.4.35"
 
-      - name: Install mdbook-template
-        run: |
-          mkdir mdbook-template
-          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
-          echo `pwd`/mdbook-template >> $GITHUB_PATH
+      # Install mdbook-katex
+      - name: Install mdbook-katex
+        run: cargo install mdbook-katex
 
-      - name: Run tests
-        run: mdbook test
+      # Build book
+      - name: build book
+        run: mdbook build
 
   lint:
     runs-on: ubuntu-latest
-    name: lint
 
     steps:
       - uses: actions/checkout@v3
-
+        with:
+          fetch-depth: 0
+
+      # Install Rust
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      # Install mdbook-linkcheck
       - name: Install mdbook-linkcheck
-        run: |
-          mkdir mdbook-linkcheck
-          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
-          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
-          chmod +x `pwd`/mdbook-linkcheck/mdbook-linkcheck
-          echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH
-
-      - name: Run linkcheck
+        run: cargo install mdbook-linkcheck
+
+      - name: linkcheck
         run: mdbook-linkcheck --standalone
 
-  build:
+  test:
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
-
-      - name: Install toolchain
-        uses: dtolnay/rust-toolchain@nightly
-      - uses: Swatinem/rust-cache@v2
+      
+      # Install Rust
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
         with:
-          cache-on-failure: true
-
-      - name: Install mdbook
-        run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-
-      - name: Install mdbook-template
-        run: |
-          mkdir mdbook-template
-          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
-          echo `pwd`/mdbook-template >> $GITHUB_PATH
-
-      - name: Build book
-        run: mdbook build documentation
-
-      - name: Build docs
-        run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc --all --no-deps
+          toolchain: stable
+          override: true
+
+      - name: test
+        run: cargo test --package documentation

.github/workflows/test.yaml

@@ -20,7 +20,7 @@ jobs:
           override: true
 
       - name: test
-        run: cargo test --workspace --all-features
+        run: cargo test --workspace --all-features --exclude documentation
 
   codecov:
     name: codecov
@@ -38,7 +38,7 @@ jobs:
         uses: taiki-e/install-action@cargo-llvm-cov
 
       - name: codecov
-        run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
+        run: cargo llvm-cov --all-features --workspace  --exclude documentation --lcov --output-path lcov.info
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v3

.gitignore

@@ -20,4 +20,6 @@ arbiter/
 book
 
 arbiter-core/data
-example_fork/test.json
+example_fork/test.json
+
+doctest_cache/

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 # List of crates included in this workspace
-members = [ "arbiter-bindings", "arbiter-core", "arbiter-engine"]
+members = [ "arbiter-bindings", "arbiter-core", "arbiter-engine", "documentation"]
 
 # List of crates excluded from this workspace
 exclude = ["benches"]

arbiter-core/src/environment/fork.rs

@@ -47,7 +47,7 @@ impl Fork {
         // Read the file
         let mut cwd = env::current_dir().unwrap();
         cwd.push(path);
-        info!("Reading db from: {:?}", cwd);
+        print!("Reading db from: {:?}", cwd);
         let data = fs::read_to_string(cwd).unwrap();
 
         // Deserialize the JSON data to your OutputData type

arbiter-core/src/environment/instruction.rs

@@ -154,6 +154,7 @@ pub(crate) enum EnvironmentData {
     /// The query is for the balance of an account given by the inner `Address`.
     Balance(ethers::types::Address),
 
+    // TODO: Rename this to `Nonce`?
     /// The query is for the nonce of an account given by the inner `Address`.
     TransactionCount(ethers::types::Address),
 }

book.toml

@@ -27,6 +27,11 @@ include-src = false
 block-delimiter = { left = "$$", right = "$$" }
 inline-delimiter = { left = "$", right = "$" }
 
+[preprocessor.keeper]
+command = "mdbook-keeper"
+manifest_dir = "./documentation/"
+externs = ["arbiter_core", "arbiter_bindings", "tokio"]
+
 [output.linkcheck]
 optional = true
 follow-web-links = true

documentation/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "documentation"
+version = "0.0.0"
+edition = "2021"
+build = "build.rs"
+
+[build-dependencies]
+skeptic = "0.13.7"
+tokio.workspace = true
+
+[dev-dependencies]
+skeptic = "0.13.7"
+arbiter-core.workspace = true
+arbiter-bindings.workspace = true
+

documentation/build.rs

@@ -0,0 +1,8 @@
+use skeptic::markdown_files_of_directory;
+
+extern crate skeptic;
+
+fn main() {
+    let markdown_files = markdown_files_of_directory("src/");
+    skeptic::generate_doc_tests(&markdown_files);
+}

documentation/src/SUMMARY.md

@@ -1,13 +1,22 @@
 # Summary
-
+[Arbiter](./index.md)
 - [Introduction](./introduction/introduction.md)
 - [Getting Started / Installation](./getting_started/getting_started.md)
   - [Setting up Simulations](./getting_started/setting_up_simulations.md)
+
+# Usage
+- [Overview](./usage/index.md)
+  - [Arbiter CLI](./usage/arbiter_cli.md)
+  - [Arbiter Core](./usage/arbiter_core.md)
+  - [Arbiter Engine](./usage/arbiter_engine.md)
+
+# Methodology
 - [Anomaly Detection](./introduction/anomaly_detection.md)
 - [Auditing](./auditing/auditing.md)
 - [Risk](./risk/risk_metrics.md)
   - [Metrics](./risk/metrics.md)
   <!-- - [Frameworks for modeling risk](./economic_risk/modeling_risk.md) -->
+# Engagement
 - [Contributing](./contributing/contributing.md)
   - [Project Architecture](./contributing/architecture.md)
   - [Vulnerability Corpus](./contributing/vulnerability_corpus.md)