Provide a Nox benchmarks session as the recommended entry point (#5951)

* Provide a Nox benchmarks session as the recommended entry point.

* What's New entry.

* Full name of help argument.

---------

Co-authored-by: stephenworsley <[email protected]>

Author: trexfeathers

.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)