ENH: Add additional environment to tox to run notebooks

Add an additional environment to `tox` to run notebooks.

Add a new table to `pyproject.toml` to host the `jupyter`, `nbclient`
and `nbmake` dependencies so that the notebooks can be run.

Install the necessary TeX packages in the test CI so that LaTeX
decoration in plots can be employed.

Install the necessary additional Python packages used across the
notebooks.

Add a helper Python script to actually run the notebooks since `tox`
does not expand wildcards currently.

.github/workflows/test.yml

@@ -70,6 +70,10 @@ jobs:
         with:
           path: /home/runner/nifreeze-tests/
           key: data-v0
+      - name: Install TeX Live
+        run: |
+          sudo apt-get update
+          sudo apt install texlive cm-super
       - name: Install tox
         run: |
           python -m pip install --upgrade pip

pyproject.toml

@@ -74,6 +74,13 @@ test = [
     "pytest-xdist >= 1.28"
 ]
 
+notebooks = [
+    "jupyter",
+    "nbclient",
+    "nbmake",
+    "nipreps-synthstrip",
+]
+
 antsopt = [
     "ConfigSpace",
     "nipreps",

tools/run_notebooks.py

@@ -0,0 +1,5 @@
+import glob
+import subprocess
+import sys
+
+sys.exit(subprocess.call(["pytest", "--nbmake"] + glob.glob("docs/notebooks/*.ipynb")))

tox.ini

@@ -2,13 +2,13 @@
 requires =
   tox>=4
 envlist =
-  py312
+  py312, notebooks
 skip_missing_interpreters = true
 
 # Configuration that allows us to split tests across GitHub runners effectively
 [gh-actions]
 python =
-  3.12: py312
+  3.12: py312, notebooks
 
 [testenv]
 description = Pytest with coverage
@@ -39,6 +39,35 @@ commands =
   pytest --doctest-modules --cov nifreeze -n auto --cov-report xml \
   --junitxml=test-results.xml -v src test {posargs}
 
+[testenv:notebooks]
+description = Run notebooks
+labels = notebooks
+pass_env =
+  # getpass.getuser() sources for Windows:
+  LOGNAME
+  USER
+  LNAME
+  USERNAME
+  # Pass user color preferences through
+  PY_COLORS
+  FORCE_COLOR
+  NO_COLOR
+  CLICOLOR
+  CLICOLOR_FORCE
+  CURBRANCH
+  GITHUB_ACTIONS
+  TEST_DATA_HOME
+  TEST_OUTPUT_DIR
+  TEST_WORK_DIR
+  PYTHONHASHSEED
+  ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS
+  PATH
+extras = notebooks
+commands =
+   # pytest --nbmake docs/notebooks/*.ipynb
+   # not working due to https://github.com/tox-dev/tox/issues/1571
+   python {toxinidir}/tools/run_notebooks.py
+
 [testenv:docs]
 description = Build documentation site
 labels = docs