clarify benchmarks in docs

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.

benchmarks/comparison/README.md

@@ -1,9 +1,25 @@
 # 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/#/
 - Comment-out parts to get the light and dark versions
 - 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

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.