From a585d7b66ed37c310282411f8f780dab120f3c77 Mon Sep 17 00:00:00 2001
From: Arie Bovenberg <a.c.bovenberg@gmail.com>
Date: Sat, 6 Jul 2024 22:01:07 +0200
Subject: [PATCH] clarify benchmarks in docs

---
 benchmarks/README.md                             |  7 +++++++
 benchmarks/comparison/README.md                  | 16 ++++++++++++++++
 .../{run_stdlib_dateutil.py => run_stdlib.py}    |  0
 docs/faq.rst                                     |  6 ++++++
 4 files changed, 29 insertions(+)
 rename benchmarks/comparison/{run_stdlib_dateutil.py => run_stdlib.py} (100%)

diff --git a/benchmarks/README.md b/benchmarks/README.md
index edef8884..1ebaf109 100644
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@ -1,2 +1,9 @@
 This folder contains code for benchmarking.
+
+There are three benchmarking directories:
+
+- ``comparison``: for comparing `whenever` with other datetime libraries.
+- ``python``: for benchmarking the library "end-to-end" in Python.
+- ``rust``: for benchmarking specific parts of the library in Rust.
+
 Benchmarking as part of CI is currently incomplete and work-in-progress.
diff --git a/benchmarks/comparison/README.md b/benchmarks/comparison/README.md
index 4aa1c44e..f2323a1c 100644
--- a/benchmarks/comparison/README.md
+++ b/benchmarks/comparison/README.md
@@ -1,5 +1,16 @@
 # Benchmark comparisons
 
+## Running the benchmarks
+
+```shell
+python benchmarks/comparison/run_whenever.py
+python benchmarks/comparison/run_stdlib.py
+python benchmarks/comparison/run_pendulum.py
+python benchmarks/comparison/run_arrow.py
+```
+
+Tip: make sure to build `whenever` in release mode before running the benchmarks!
+
 ## Generating the graphs
 
 - Copy the `graph-vega-config.json` into https://vega.github.io/editor/#/
@@ -7,3 +18,8 @@
 - Export as svg
 - Add `font-weight="bold"` to the first appearance of "Whenever"
 - Set `width="500"` and `height="127"`
+
+## Setup for the benchmark in the main README
+
+The benchmarking graph in the main README was generated on
+a 2021 M1 Pro Macbook, MacOS 14.5 on Python 3.12.2
diff --git a/benchmarks/comparison/run_stdlib_dateutil.py b/benchmarks/comparison/run_stdlib.py
similarity index 100%
rename from benchmarks/comparison/run_stdlib_dateutil.py
rename to benchmarks/comparison/run_stdlib.py
diff --git a/docs/faq.rst b/docs/faq.rst
index c4f08011..c75141bd 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -106,3 +106,9 @@ The core functionality is complete and mostly stable.
 The goal is to reach 1.0 soon, but the API may change until then.
 Of course, it's still a relatively young project, so the stability relies
 on you to try it out and report any issues!
+
+Where do the benchmarks come from?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+More information about the benchmarks can be found in the ``benchmarks`` directory
+of the repository.