Set up multi-version docs (#111)

* use multi-version action

* configure version switcher

* fix movement URLs

* lowe pin movement dependency

* fix typo

* linkcheck ignore figshare

* update binder config to work with multiversion

* Update docs/source/conf.py

Signed-off-by: sfmig <33267254+sfmig@users.noreply.github.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Check fix for 403

* Revert "Check fix for 403"

This reverts commit 491a8a7.

* Use mirror in data release

---------

Signed-off-by: sfmig <33267254+sfmig@users.noreply.github.com>
Co-authored-by: sfmig <33267254+sfmig@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

.binder/.postBuild

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# This script runs in a Binder context within a git checkout of the
+# neuroinformatics-unit/ethology repository. It generates Jupyter notebooks
+# from the ethology 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/ethology-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 @@
+. # ethology itself

.binder/runtime.txt

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

.github/workflows/docs_build_and_deploy.yml

@@ -59,7 +59,8 @@ jobs:
     if: (github.event_name == 'push' && (github.ref == 'refs/heads/main' || needs.check_tag.outputs.tag_on_main == 'true')) || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
-      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@v2
+      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs_multiversion@v2
         with:
           secret_input: ${{ secrets.GITHUB_TOKEN }}
           use-make: true
+          switcher-url: https://ethology.neuroinformatics.dev/latest/_static/switcher.json

CONTRIBUTING.md

@@ -300,7 +300,17 @@ make clean html linkcheck
 ```
 :::
 
+We use [sphinx-gallery](sphinx-gallery:)
+to create the [examples](target-examples).
+To add new examples, you will need to create a new `.py` file in `examples/`.
+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.
+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 `.binder/requirements.txt` file.
 
 ## Test data
 

MANIFEST.in

@@ -10,6 +10,7 @@ recursive-exclude docs *
 recursive-exclude tests *
 recursive-exclude examples *
 recursive-include docs *
+recursive-include .binder *
 
 # Include json schemas
 recursive-include ethology/validators/json_schemas/schemas *.json

docs/source/community/related-projects.md

@@ -1,3 +1,3 @@
 # Related projects
 
-We are the same developer team as the one behind [`movement`](https://movement.neuroinformatics.dev/index.html#), a Python package for analysing animal body movements across space and time. We interact very closely with their community to make sure our tools are interoperable and we follow very similar conventions and standards.
+We are the same developer team as the one behind [`movement`](https://movement.neuroinformatics.dev), a Python package for analysing animal body movements across space and time. We interact very closely with their community to make sure our tools are interoperable and we follow very similar conventions and standards.

docs/source/conf.py

@@ -26,6 +26,10 @@
     # with a dummy version
     release = "0.0.0"
 
+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
 
@@ -117,6 +121,11 @@
             "type": "fontawesome",
         },
     ],
+    "switcher": {
+        "json_url": "https://ethology.neuroinformatics.dev/latest/_static/switcher.json",
+        "version_match": doc_version,
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "logo": {
         "text": f"{project} v{release}",
     },
@@ -151,7 +160,9 @@
 ]
 # A list of regular expressions that match URIs that should not be checked
 linkcheck_ignore = [
-    "https://opensource.org/license/bsd-3-clause/",  # to avoid odd 403 error
+    # to avoid odd 403 client errors
+    "https://opensource.org/license/bsd-3-clause/",
+    "https://figshare.com/articles/dataset/Australian_Camera_Trap_Data_ACTD_/27177912",
 ]
 
 myst_url_schemes = {
@@ -227,9 +238,9 @@
     "binder": {
         "org": "neuroinformatics-unit",
         "repo": "ethology",
-        "branch": "gh-pages",
+        "branch": binder_branch,  # Can be any branch, tag, or commit
         "binderhub_url": "https://mybinder.org",
-        "dependencies": ["environment.yml"],
+        "dependencies": ["../../.binder/requirements.txt"],
     },
     "reference_url": {"ethology": None},
     "default_thumb_file": "source/_static/dark-logo-niu.png",

docs/source/environment.yml

@@ -74,14 +74,16 @@
 # For this example, we will use the `Australian Camera Trap Dataset
 # <https://figshare.com/articles/dataset/Australian_Camera_Trap_Data_ACTD_/27177912>`_
 # which comprises images from camera traps across various sites in Victoria,
-# Australia.
+# Australia. This dataset is licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
+# and authored by  Sameeruddin Muhammad, Scott Mann, Callum Luke,
+# Chris Pocknee, Supriya Nair and Jay Nair.
 #
 # We use the `pooch <https://github.com/fatiando/pooch/>`_ library to download
 # the dataset to the ``.ethology`` cache directory.
 
 # %%
 data_source = {
-    "url": "https://figshare.com/ndownloader/files/53674187",
+    "url": "https://github.com/neuroinformatics-unit/ethology/releases/download/data-ACTD/ACTD_COCO_files.zip",
     "hash": "4019bb11cd360d66d13d9309928195638adf83e95ddec7b0b23e693ec8c7c26b",
 }