Provide a Nox benchmarks session as the recommended entry point

.github/workflows/benchmarks_run.yml

@@ -71,9 +71,9 @@ jobs:
  with:
  fetch-depth: 0
 
- - name: Install ASV & Nox
+ - name: Install Nox
  run: |
- pip install asv nox
+ pip install nox
 
  - name: Cache environment directories
  id: cache-env-dir
@@ -112,7 +112,7 @@ jobs:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  PR_NUMBER: ${{ github.event.number }}
  run: |
- python benchmarks/bm_runner.py branch origin/${{ github.base_ref }}
+ nox -s benchmarks -- branch origin/${{ github.base_ref }}
 
  - name: Run overnight benchmarks
  id: overnight
@@ -128,7 +128,7 @@ jobs:
 
  if [ "$first_commit" != "" ]
  then
- python benchmarks/bm_runner.py overnight $first_commit
+ nox -s benchmarks -- overnight $first_commit
  fi
 
  - name: Warn of failure

benchmarks/README.md

@@ -20,13 +20,13 @@ the PR's base branch, thus showing performance differences introduced
 by the PR. (This run is managed by 
 [the aforementioned GitHub Action](../.github/workflows/benchmark.yml)).
 
-`asv ...` commands must be run from this directory. You will need to have ASV
-installed, as well as Nox (see
-[Benchmark environments](#benchmark-environments)).
-
-The benchmark runner ([bm_runner.py](./bm_runner.py)) provides conveniences for
+To run locally: the **benchmark runner** provides conveniences for
 common benchmark setup and run tasks, including replicating the automated 
-overnight run locally. See `python bm_runner.py --help` for detail.
+overnight run locally. This is accessed via the Nox `benchmarks` session - see
+`nox -s benchmarks -- --help` for detail (_see also: 
+[bm_runner.py](./bm_runner.py)_). Alternatively you can directly run `asv ...`
+commands from this directory (you will still need Nox installed - see
+[Benchmark environments](#benchmark-environments)).
 
 A significant portion of benchmark run time is environment management. Run-time
 can be reduced by placing the benchmark environment on the same file system as

docs/src/whatsnew/latest.rst

@@ -102,6 +102,9 @@ This document explains the changes made to Iris for this release
  benchmark runs, and introduced larger more 'real world' benchmarks where
  coverage was needed. (:pull:`5949`).
 
+#. `@trexfeathers`_ made a Nox `benchmarks` session as the recommended entry
+ point for running benchmarks. (:pull:`5951`)
+
 
 .. comment
  Whatsnew author names (@github name) in alphabetical order. Note that,

noxfile.py

@@ -291,3 +291,27 @@ def wheel(session: nox.sessions.Session):
  "import iris; print(f'{iris.__version__=}')",
  external=True,
  )
+
+
+@nox.session
+def benchmarks(session: nox.sessions.Session):
+ """Run the Iris benchmark runner. Run session with `-- --help` for help.
+
+ Parameters
+ ----------
+ session : object
+ A `nox.sessions.Session` object.
+
+ """
+ if len(session.posargs) == 0:
+ message = (
+ "This session MUST be run with at least one argument. The "
+ "arguments are passed down to the benchmark runner script. E.g:\n"
+ "nox -s benchmarks -- --help\n"
+ "nox -s benchmarks -- something --help\n"
+ "nox -s benchmarks -- something\n"
+ )
+ session.error(message)
+ session.install("asv", "nox")
+ with session.chdir(Path(__file__).parent / "benchmarks"):
+ session.run("python", "bm_runner.py", *session.posargs)