Update docs with current interface (#24)

- Added examples to the documentation (#34). - Updated logo with a simpler image. - Split README information into different files within the docs folder. - Added usage example with Slurm. - Included example YAML demonstrating various Spinner functionalities.
LSC-Unicamp · Aug 15, 2024 · 5e4768d · 5e4768d
1 parent d4fbaed
commit 5e4768d
Show file tree

Hide file tree

Showing 10 changed files with 207 additions and 318 deletions.
diff --git a/README.md b/README.md
@@ -1,86 +1,33 @@
 # Spinner
 
-![Logo](spinner.svg)
+<img src="spinner.png" alt="drawing" width="200"/>
+
+## Contributting
+Read the [Contribution Guidelines](docs/contribute.md).
 
 ## Setting up environment
 
 ```sh
+python3 -m ensurepip
+python3 -m pip3 install virtualenv
 python3 -m virtualenv .venv
-python3 -m pip install pip --upgrade
-python -m pip install ".[dev]"
 source .venv/bin/activate
+python3 -m pip install pip --upgrade
+python -m pip install .
 ```
 
 ## Running
-```sh
-python3 spinner/main.py -b F -r T -c spinner/bench_settings.yaml -e F
 
-python3 spinner/main.py -g T -s 1000000000 -o random_numbers.bin -r T -c spinner/bench_settings.yaml -e T -h "sdumont[6174-6177]"
-```
+Check examples in the docs folder. Check plotting examples in the notebook `spinner/exporter/reporter.ipynb`. This is the notebook that the command `--export` uses.
 
-# Mandatory development policy
-`.git/hooks/pre-commit`
 ```sh
-#!/bin/bash
-
-if git rev-parse --verify HEAD >/dev/null 2>&1; then
-    against=HEAD
-else
-    # Initial commit: diff against an empty tree object
-    against=4b825dc642cb6eb9a060e54bf8d69288fbee4904
-fi
-
-# Function to format all C/C++ files using clang-format
-format_c_cpp_files() {
-    if command -v clang-format >/dev/null 2>&1; then
-        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.(c|h|cpp|hpp)$'); do
-            clang-format -i "$file"
-            git add "$file"
-        done
-    else
-        echo "clang-format not found, skipping C/C++ file formatting."
-    fi
-}
-
-# Function to format all Python files using black
-format_python_files() {
-    if command -v black >/dev/null 2>&1; then
-        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.py$'); do
-            black "$file"
-            isort "$file"
-            git add "$file"
-        done
-    else
-        echo "black not found, skipping Python file formatting."
-    fi
-    if command -v black >/dev/null 2>&1; then
-        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.ipynb$'); do
-            black "$file"
-            isort "$file"
-            git add "$file"
-        done
-    else
-        echo "black for notebook not found, skipping Python file formatting."
-    fi
-}
-
-# Function to clear output in Jupyter notebooks
-clear_notebook_output() {
-    if command -v jupyter >/dev/null 2>&1; then
-        for notebook in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.ipynb$'); do
-            jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace "$notebook"
-            git add "$notebook"
-        done
-    else
-        echo "jupyter not found, skipping Jupyter notebook output clearing."
-    fi
-}
-
-# Run the formatting functions
-format_c_cpp_files
-format_python_files
-clear_notebook_output
-
-# Check for changes
-exec git diff-index --check --cached "$against" --
+spinner --help
+Usage: spinner [OPTIONS]
+
+Options:
+  -c, --config TEXT     Benchmark configuration file
+  -r, --run BOOLEAN     Run all benchmarks
+  -e, --export BOOLEAN  Export results to report.html
+  -h, --hosts TEXT      Hosts list
+  --help                Show this message and exit.
 ```
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -0,0 +1,80 @@
+# Contribute to Spinner
+
+## Setting up the environment as a developer
+
+```sh
+python3 -m ensurepip
+python3 -m pip3 install virtualenv
+python3 -m virtualenv .venv
+source .venv/bin/activate
+python3 -m pip install pip --upgrade
+python -m pip install -e ".[dev]"
+```
+
+## Mandatory lint policy
+
+We recomend the following commit hook (`.git/hooks/pre-commit`)
+```sh
+#!/bin/bash
+
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+    against=HEAD
+else
+    # Initial commit: diff against an empty tree object
+    against=4b825dc642cb6eb9a060e54bf8d69288fbee4904
+fi
+
+# Function to format all C/C++ files using clang-format
+format_c_cpp_files() {
+    if command -v clang-format >/dev/null 2>&1; then
+        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.(c|h|cpp|hpp)$'); do
+            clang-format -i "$file"
+            git add "$file"
+        done
+    else
+        echo "clang-format not found, skipping C/C++ file formatting."
+    fi
+}
+
+# Function to format all Python files using black
+format_python_files() {
+    if command -v black >/dev/null 2>&1; then
+        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.py$'); do
+            black "$file"
+            isort "$file"
+            git add "$file"
+        done
+    else
+        echo "black not found, skipping Python file formatting."
+    fi
+    if command -v black >/dev/null 2>&1; then
+        for file in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.ipynb$'); do
+            black "$file"
+            isort "$file"
+            git add "$file"
+        done
+    else
+        echo "black for notebook not found, skipping Python file formatting."
+    fi
+}
+
+# Function to clear output in Jupyter notebooks
+clear_notebook_output() {
+    if command -v jupyter >/dev/null 2>&1; then
+        for notebook in $(git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.ipynb$'); do
+            jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace "$notebook"
+            git add "$notebook"
+        done
+    else
+        echo "jupyter not found, skipping Jupyter notebook output clearing."
+    fi
+}
+
+# Run the formatting functions
+format_c_cpp_files
+format_python_files
+clear_notebook_output
+
+# Check for changes
+exec git diff-index --check --cached "$against" --
+```
diff --git a/docs/examples/capture_output.yaml b/docs/examples/capture_output.yaml
@@ -0,0 +1,41 @@
+metadata:
+  description: shell time capture output
+  version: "1.0"
+  runs: 5
+  timeout: 7
+  retry: True
+  retry_limit: 0
+
+  sleep_test:
+    command:
+      template: >
+        bash -c "time sleep {{sleep_ammount}}"
+
+    output:
+      - type: contains
+        pattern: "real"
+        to_float:
+          name: real_time
+          lambda: >
+            lambda x:  (
+            float(x.split("m")[0].split("\t")[1]) * 60
+            +
+            float(x.split("m")[1].split("s")[0])
+            )
+
+
+    plot_axis:
+      - title: Real Time vs Sleep arg
+        x_axis: sleep_ammount
+        y_axis: real_time
+        group_by: sleep_ammount
+
+      - title: Measure Time vs sleep arg
+        x_axis: sleep_ammount
+        y_axis: time
+        group_by: sleep_ammount
+
+sleep_test:
+  sleep_ammount:
+    - 0.31
+    - 0.28
diff --git a/docs/examples/sleep_benchmark.yaml b/docs/examples/sleep_benchmark.yaml
@@ -0,0 +1,19 @@
+metadata:
+  description: Sleep check
+  version: "1.0"
+  runs: 2
+  timeout: 5
+  retry: True
+  retry_limit: 0
+
+  sleep_test:
+    command:
+      template: >
+        sleep {{sleep_ammount}} && printf "
+        I slept {{sleep_ammount}}
+        "
+
+sleep_test:
+  sleep_ammount:
+    - 1
+    - 2
diff --git a/docs/examples/timeout_test.yaml b/docs/examples/timeout_test.yaml
@@ -0,0 +1,20 @@
+metadata:
+  description: Timeout test
+  version: "1.0"
+  runs: 1
+  timeout: 5
+  retry: False
+  retry_limit: 0
+
+  sleep_test:
+    command:
+      template: >
+        sleep {{sleep_ammount}} && printf "
+        I slept {{sleep_ammount}}
+        # this may not print due to timeout!
+        "
+
+sleep_test:
+  sleep_ammount:
+    - 1
+    - 200