Merge pull request #518 from predictive-clinical-neuroscience/contsil… #105
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Execute all tutorial notebooks and commit the results. | |
| # | |
| # Triggers: | |
| # - Push: runs automatically when the commit title contains | |
| # "[full doc]" (on any branch). | |
| # - Manual: open the Actions tab, select "Run Notebooks", | |
| # click "Run workflow". Pick a branch and optionally tick | |
| # "Dry run" to execute without committing. | |
| # | |
| # The workflow stops immediately if any notebook fails. | |
| # The failing notebook name and cell error are printed in the log. | |
| # Nothing is committed unless every notebook succeeds. | |
| # | |
| # Notebook 08_cluster.ipynb is always skipped — it requires SLURM. | |
| # Notebook 14_longitudinal_modelling.ipynb is temporarily skipped. | |
| name: Run Notebooks | |
| on: | |
| push: | |
| branches: | |
| - '**' | |
| workflow_dispatch: | |
| inputs: | |
| dry_run: | |
| description: > | |
| Dry run — execute notebooks but do NOT commit results back. | |
| required: false | |
| type: boolean | |
| default: false | |
| permissions: | |
| contents: write # required to push committed outputs back | |
| jobs: | |
| run-notebooks: | |
| # Run when the commit title contains [full doc], or when | |
| # triggered manually via workflow_dispatch. | |
| if: > | |
| contains(github.event.head_commit.message, '[full doc]') || | |
| github.event_name == 'workflow_dispatch' | |
| runs-on: ubuntu-latest | |
| steps: | |
| # ── 1. Checkout ──────────────────────────────────────────── | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| # persist-credentials lets the final push step use the | |
| # built-in GITHUB_TOKEN — no personal access token needed. | |
| persist-credentials: true | |
| # ── 2. Python ────────────────────────────────────────────── | |
| - name: Set up Python 3.13 | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.13" | |
| # ── 3. System dependencies ───────────────────────────────── | |
| - name: Install pandoc | |
| # pandoc is required by nbconvert --to rst, which is called | |
| # by doc/convert_notebooks.py in step 6. | |
| run: sudo apt-get install -y pandoc | |
| # ── 4. Python dependencies ───────────────────────────────── | |
| - name: Install Python dependencies | |
| run: | | |
| # Install the package plus its dev extras, then add | |
| # papermill for notebook execution. | |
| pip install -e ".[dev]" | |
| pip install papermill | |
| # ── 5. Execute all notebooks ─────────────────────────────── | |
| - name: Execute notebooks | |
| run: | | |
| # Loop over every notebook in examples/, skipping the | |
| # cluster notebook which requires SLURM and cannot run | |
| # in a GitHub Actions environment. | |
| FAILED=0 | |
| for nb in examples/*.ipynb; do | |
| if [[ "$nb" == *"08_cluster"* ]]; then | |
| echo "Skipping (SLURM-only): $nb" | |
| continue | |
| fi | |
| if [[ "$nb" == *"14_longitudinal"* ]]; then | |
| echo "Skipping (temporarily disabled): $nb" | |
| continue | |
| fi | |
| echo "Running: $nb" | |
| # papermill executes the notebook in-place and prints | |
| # the failing cell + Python traceback on error. | |
| papermill "$nb" "$nb" \ | |
| --execution-timeout 3600 \ | |
| --request-save-on-cell-execute \ | |
| || { echo "FAILED: $nb"; FAILED=1; break; } | |
| echo "Done: $nb" | |
| done | |
| # Exit with failure so GitHub Actions marks the job red | |
| # and shows the error prominently. | |
| exit $FAILED | |
| # ── 6. Convert notebooks to RST ─────────────────────────── | |
| - name: Convert notebooks to RST | |
| # Regenerate all RST files from the freshly executed .ipynb | |
| # files so the website outputs are up to date. | |
| run: python doc/convert_notebooks.py | |
| # ── 7. Commit and push ───────────────────────────────────── | |
| - name: Commit generated outputs | |
| # Skip commit on manual dry-run; always commit on push | |
| # trigger (dry_run input is empty for push events, so | |
| # comparing != 'true' handles both cases correctly). | |
| if: ${{ github.event.inputs.dry_run != 'true' }} | |
| run: | | |
| git config --global user.name "github-actions[bot]" | |
| git config --global user.email \ | |
| "github-actions[bot]@users.noreply.github.com" | |
| # Stage the executed notebooks and the generated RST files. | |
| git add examples/ doc/tutorials/ | |
| # Commit only if there are staged changes; exit cleanly | |
| # if nothing changed (idempotent re-runs are safe). | |
| if git diff --staged --quiet; then | |
| echo "Nothing changed — no commit needed." | |
| else | |
| git commit -m \ | |
| "doc: update executed notebook outputs [skip ci]" | |
| git push | |
| fi |