Dev/prvep experiment with docs

.gitattributes

@@ -0,0 +1,19 @@
+# Force LF line endings for WSL and cross-platform (Linux/Mac/GitHub Actions) compatibility
+# This prevents obscure bugs when running Windows-edited scripts on Linux runners.
+* text=auto eol=lf
+
+*.py        text eol=lf
+*.rst       text eol=lf
+*.md        text eol=lf
+*.yml       text eol=lf
+*.yaml      text eol=lf
+*.cfg       text eol=lf
+*.toml      text eol=lf
+*.ipynb     text eol=lf
+
+*.png       binary
+*.jpg       binary
+*.jpeg      binary
+*.gif       binary
+*.ico       binary
+*.pdf       binary

.github/actions/setup-conda-env/action.yml

@@ -0,0 +1,32 @@
+name: Set up conda env
+description: >
+  Install Miniconda and create/activate an EEG-ExPy conda environment from
+  the given env yml. Shared by the Test and Typecheck jobs so the two
+  don't drift apart. Environment name is not set in the yml files so local
+  installs can use any name they like.
+
+inputs:
+  environment-file:
+    required: true
+    description: Path to the conda environment yml file to install from.
+  activate-environment:
+    required: true
+    description: Name to give the created environment.
+  python-version:
+    required: false
+    description: >
+      Python version to pin (e.g. '3.8'). Overrides the version conda would
+      otherwise resolve from the environment file's constraints. When omitted,
+      conda resolves freely within the environment file's range.
+
+runs:
+  using: composite
+  steps:
+    - uses: conda-incubator/setup-miniconda@v3
+      with:
+        environment-file: ${{ inputs.environment-file }}
+        activate-environment: ${{ inputs.activate-environment }}
+        python-version: ${{ inputs.python-version }}
+        auto-activate-base: false
+        channels: conda-forge
+        miniconda-version: "latest"

.github/workflows/docs.yml

@@ -9,29 +9,20 @@ on:
 jobs:
   build:
     runs-on: ubuntu-22.04
+    defaults:
+      run:
+        shell: bash -el {0}
     steps:
     - name: Checkout repo
       uses: actions/checkout@v3
       with:
-        fetch-depth: 0   
-
-    - name: Set up Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.8
-
-    - name: Install dependencies
-      run: |
-        make install-deps-apt
-        python -m pip install --upgrade pip wheel
-        python -m pip install attrdict
-
-        make install-deps-wxpython
-
-    - name: Build project
-      run: |
-        make install-docs-build-dependencies
+        fetch-depth: 0
 
+    - name: Set up conda env
+      uses: ./.github/actions/setup-conda-env
+      with:
+        environment-file: environments/eeg-expy-docsbuild.yml
+        activate-environment: eeg-expy-docsbuild
 
     - name: Get list of changed files
       id: changes
@@ -40,21 +31,20 @@ jobs:
         git diff --name-only origin/master...HEAD > changed_files.txt
         cat changed_files.txt
 
-
     - name: Determine build mode
       id: mode
       run: |
         if grep -vqE '^examples/.*\.py$' changed_files.txt; then
           echo "FULL_BUILD=true" >> $GITHUB_ENV
           echo "Detected non-example file change. Full build triggered."
         else
-          CHANGED_EXAMPLES=$(grep '^examples/.*\.py$' changed_files.txt | paste -sd '|' -)
+          # || true prevents grep's exit code 1 (no matches) from aborting the step
+          CHANGED_EXAMPLES=$(grep '^examples/.*\.py$' changed_files.txt | paste -sd '|' - || true)
           echo "FULL_BUILD=false" >> $GITHUB_ENV
           echo "CHANGED_EXAMPLES=$CHANGED_EXAMPLES" >> $GITHUB_ENV
           echo "Changed examples: $CHANGED_EXAMPLES"
         fi
 
-
     - name: Cache built documentation
       id: cache-docs
       uses: actions/cache@v4
@@ -65,15 +55,12 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-sphinx-
 
-
     - name: Build docs
-      run: |
-        make docs
+      run: make docs
 
-
     - name: Deploy Docs
       uses: peaceiris/actions-gh-pages@v3
-      if: github.ref == 'refs/heads/master'  # TODO: Deploy seperate develop-version of docs?
+      if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/dev/')
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: doc/_build/html

.github/workflows/test.yml

@@ -13,38 +13,47 @@ jobs:
     defaults:
       run:
         shell: bash -el {0}
+    continue-on-error: ${{ matrix.experimental == true }}
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu-22.04', windows-latest, macOS-latest]
-        python_version: ['3.8']
+        os: [ubuntu-22.04, windows-latest, macOS-latest]
+        python_version: ['3.10']
+        env_file: [environments/eeg-expy-full.yml]
+        env_name: [eeg-expy-full]
         include:
-          # PsychoPy currently restricted to <= 3.10
+          # Experimental Full Build: Catch regressions on 3.11 early
           - os: ubuntu-22.04
-            python_version: '3.10'
+            python_version: '3.11'
+            experimental: true
+            env_file: environments/eeg-expy-full.yml
+            env_name: eeg-expy-full
+
+          # Experimental Streaming Builds: Verify acquisition/analysis on 3.12+
+          - os: ubuntu-22.04
+            python_version: '3.12'
+            experimental: true
+            env_file: environments/eeg-expy-streaming.yml
+            env_name: eeg-expy-streaming
+          - os: ubuntu-22.04
+            python_version: '3.13'
+            experimental: true
+            env_file: environments/eeg-expy-streaming.yml
+            env_name: eeg-expy-streaming
 
     steps:
     - uses: actions/checkout@v2
     - name: Install APT dependencies
       if: "startsWith(runner.os, 'Linux')"
       run: |
         make install-deps-apt
-    - name: Install conda
-      uses: conda-incubator/setup-miniconda@v3
+    - name: Set up conda env
+      uses: ./.github/actions/setup-conda-env
       with:
-        environment-file: environments/eeg-expy-full.yml
-        auto-activate-base: false
+        environment-file: ${{ matrix.env_file }}
+        activate-environment: ${{ matrix.env_name }}
         python-version: ${{ matrix.python_version }}
-        activate-environment: eeg-expy-full
-        channels: conda-forge
-        miniconda-version: "latest"
-
-    - name: Fix PsychXR numpy dependency DLL issues (Windows only)
-      if: matrix.os == 'windows-latest'
-      run: |
-        conda install --force-reinstall numpy
-
-    - name: Run eegnb install test
+    - name: Run eeg-expy install test
       run: |
         if [ "$RUNNER_OS" == "Linux" ]; then
           Xvfb :0 -screen 0 1024x768x24 -ac +extension GLX +render -noreset &> xvfb.log &
@@ -58,7 +67,7 @@ jobs:
           Xvfb :0 -screen 0 1024x768x24 -ac +extension GLX +render -noreset &> xvfb.log &
           export DISPLAY=:0
         fi
-        make test PYTEST_ARGS="--ignore=tests/test_run_experiments.py"
+        make test
 
 
   typecheck:
@@ -71,19 +80,16 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-22.04']
-        python_version: [3.9]
+        python_version: ['3.10']
 
     steps:
     - uses: actions/checkout@v2
-    - name: Install conda
-      uses: conda-incubator/setup-miniconda@v3
+    - name: Set up conda env
+      uses: ./.github/actions/setup-conda-env
       with:
         environment-file: environments/eeg-expy-full.yml
-        auto-activate-base: false
-        python-version: ${{ matrix.python_version }}
         activate-environment: eeg-expy-full
-        channels: conda-forge
-        miniconda-version: "latest"
+        python-version: ${{ matrix.python_version }}
     - name: Typecheck
       run: |
         make typecheck

.gitignore

@@ -6,10 +6,15 @@ __pycache__
 # Built as part of docs
 doc/auto_examples
 doc/_build
+doc/generated/
+doc/sg_execution_times.rst
 
 # Built by auto_examples
 examples/visual_cueing/*.csv
 
+# Jupytext-paired notebooks (the .py is the source of truth; .ipynb is auto-paired)
+**.ipynb
+
 # tests/coverage artifacts
 .coverage
 coverage.xml
@@ -18,4 +23,4 @@ htmlcov
 # PyCharm
 .idea/
 
-**/.DS_Store
+**/.DS_Store

conftest.py

@@ -0,0 +1,19 @@
+import importlib.util
+
+
+def _is_available(module_name: str) -> bool:
+    try:
+        return importlib.util.find_spec(module_name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+collect_ignore: list[str] = []
+
+if not _is_available("psychopy"):
+    collect_ignore += [
+        "eegnb/experiments",
+        "eegnb/devices/vr.py",
+    ]
+elif not _is_available("psychxr"):
+    collect_ignore += ["eegnb/devices/vr.py"]

doc/conf.py

@@ -255,9 +255,9 @@ def setup(app):
 
 # Configurations for sphinx gallery
 
-sphinx_gallery_conf = {'filename_pattern': '(?=.*r__)(?=.*.py)', 
-                       'examples_dirs': ['../examples','../examples/visual_n170', '../examples/visual_p300','../examples/visual_ssvep', '../examples/visual_cueing', '../examples/visual_gonogo'],
-                       'gallery_dirs': ['auto_examples','auto_examples/visual_n170', 'auto_examples/visual_p300','auto_examples/visual_ssvep', 'auto_examples/visual_cueing', 'auto_examples/visual_gonogo'],
+sphinx_gallery_conf = {'filename_pattern': '(?=.*r__)(?=.*.py)',
+                       'examples_dirs': ['../examples/visual_n170', '../examples/visual_p300','../examples/visual_ssvep', '../examples/visual_cueing', '../examples/visual_gonogo'],
+                       'gallery_dirs': ['auto_examples/visual_n170', 'auto_examples/visual_p300','auto_examples/visual_ssvep', 'auto_examples/visual_cueing', 'auto_examples/visual_gonogo'],
                        'within_subsection_order': FileNameSortKey,
                        'default_thumb_file': 'img/eeg-notebooks_logo.png',
                        'backreferences_dir': 'generated',   # Where to drop linking files between examples & API