Skip to content

Revamp Binder configuration to work with multi-version docs #718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
niksirbi merged 12 commits into from
Jan 8, 2026
Merged

Revamp Binder configuration to work with multi-version docs #718

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
c7955f4
update sphinx-gallery binder config
niksirbi Dec 5, 2025
5ef8e7c
add .binder folder with postBuild script to generate notebooks
niksirbi Dec 5, 2025
a01d99c
update contributing guide
niksirbi Dec 5, 2025
bed841a
fixes based on nilearn setup
niksirbi Dec 5, 2025
d180d1a
include local movement in requirement.txt instead of the postBuild sc…
niksirbi Dec 5, 2025
f7c4862
do not include runtime.txt ad a binder dependency
niksirbi Dec 5, 2025
fbdd976
fixed requirements.txt file
niksirbi Dec 5, 2025
4957e8f
rephrase attribution in postBuild script
niksirbi Dec 5, 2025
58528bb
rephrase comment in postBuild
niksirbi Dec 5, 2025
6cbfbbc
fix copying of notebooks
niksirbi Dec 5, 2025
2ee64c0
Apply suggestions from code review
niksirbi Jan 7, 2026
bb154f7
ensure examples structure is preserved under notebooks
niksirbi Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .binder/postBuild
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/
3 changes: 3 additions & 0 deletions .binder/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
. # movement itself
networkx
sphinx-gallery
1 change: 1 addition & 0 deletions .binder/runtime.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
python-3.13
10 changes: 4 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
1 change: 1 addition & 0 deletions MANIFEST.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,4 @@ recursive-exclude * *.py[co]
recursive-exclude docs *
recursive-exclude examples *
recursive-exclude tests *
recursive-exclude .binder *
11 changes: 6 additions & 5 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 0 additions & 10 deletions docs/source/environment.yml
View file
Open in desktop

This file was deleted.