Revamp Binder configuration to work with multi-version docs

.binder/postBuild

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# This script runs in a Binder context within a git checkout of the
+# neuroinformatics-unit/movement repository. It generates Jupyter notebooks
+# from the movement Python examples.
+# The script was adapted from https://github.com/scikit-learn/scikit-learn/blob/1.8.0rc1/.binder/postBuild
+
+set -euo pipefail       # fail immediately on errors and undefined vars
+
+# Safety check: exit if not running inside a docker container.
+: "${REPO_DIR:?This script is for repo2docker and REPO_DIR must be set. \
+Exiting because this script can delete data if run outside of a repo2docker context.}"
+
+# Create a temporary directory for staging the examples
+TMP_DIR=$(mktemp -d /tmp/movement-XXXXXX)
+# Clean up temporary directory on exit
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# Stage the examples in a temporary directory
+cp -r examples "$TMP_DIR/"
+# Recursively convert all python scripts to notebooks
+find "$TMP_DIR/examples" -name '*.py' -exec sphinx_gallery_py2jupyter '{}' +
+# Remove all non-notebook files
+find "$TMP_DIR/examples" -type f ! -name '*.ipynb' -delete
+
+# Remove everything except the existing .binder folder to present a clean workspace
+# (the .binder folder is kept for debugging purposes)
+find . -mindepth 1 -maxdepth 1 ! -name '.binder' -exec rm -rf {} +
+
+# Move the generated notebook files to where Binder expects
+mkdir -p notebooks
+mv "$TMP_DIR/examples" notebooks/

.binder/requirements.txt

@@ -0,0 +1,3 @@
+.   # movement itself
+networkx
+sphinx-gallery

.binder/runtime.txt

@@ -0,0 +1 @@
+python-3.13

CONTRIBUTING.md

@@ -300,13 +300,11 @@ or in `examples/advanced/` if your example targets experienced users.
 The file should be structured as specified in the relevant
 [sphinx-gallery documentation](sphinx-gallery:syntax).
 
-We are using sphinx-gallery's [integration with binder](sphinx-gallery:configuration#binder-links)
-to provide interactive versions of the examples.
+We are using sphinx-gallery's [integration with binder](sphinx-gallery:configuration#binder-links), to provide interactive versions of the examples.
+This is configured in `docs/source/conf.py` under the `sphinx_gallery_conf` variable,
+and further customised for our repository by the `.binder/postBuild` script.
 If your examples rely on packages that are not among `movement`'s dependencies,
-you will need to add them to the `docs/source/environment.yml` file.
-That file is used by binder to create the conda environment in which the
-examples are run. See the relevant section of the
-[binder documentation](https://mybinder.readthedocs.io/en/latest/using/config_files.html).
+you will need to add them to the `.binder/requirements.txt` file.
 
 ### Cross-referencing Python objects
 :::{note}

MANIFEST.in

@@ -10,3 +10,4 @@ recursive-exclude * *.py[co]
 recursive-exclude docs *
 recursive-exclude examples *
 recursive-exclude tests *
+recursive-exclude .binder *

docs/source/conf.py

@@ -31,7 +31,10 @@
     # with a dummy version
     release = "0.0.0"
 
-doc_version = "dev" if "dev" in release else f"v{release}"
+is_dev = "dev" in release
+doc_version = "dev" if is_dev else f"v{release}"
+binder_branch = "main" if is_dev else f"v{release}"
+
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -111,11 +114,9 @@
     "binder": {
         "org": "neuroinformatics-unit",
         "repo": "movement",
-        "branch": "gh-pages",
+        "branch": binder_branch,  # Can be any branch, tag, or commit hash
         "binderhub_url": "https://mybinder.org",
-        "dependencies": ["environment.yml"],
-        "filepath_prefix": doc_version,   # point to the versioned docs build folder inside the `gh-pages` branch
-        "notebooks_dir": "notebooks",     # default, but explicit is nice
+        "dependencies": ["../../.binder/requirements.txt"],
     },
     "reference_url": {"movement": None},
     "default_thumb_file": "source/_static/data_icon.png",  # default thumbnail image