ENH: Port over GUIs (#3)

Co-authored-by: Eric Larson <[email protected]>

.circleci/config.yml

@@ -1,26 +1,142 @@
-# Use the latest 2.1 version of CircleCI pipeline process engine.
-# See: https://circleci.com/docs/configuration-reference
 version: 2.1
-
-# Define a job to be invoked later in a workflow.
-# See: https://circleci.com/docs/configuration-reference/#jobs
 jobs:
-  say-hello:
-    # Specify the execution environment. You can specify an image from Docker Hub or use one of our convenience images from CircleCI's Developer Hub.
-    # See: https://circleci.com/docs/configuration-reference/#executor-job
-    docker:
-      - image: cimg/base:stable
-    # Add steps to the job
-    # See: https://circleci.com/docs/configuration-reference/#steps
-    steps:
-      - checkout
-      - run:
-          name: "Say hello"
-          command: "echo Hello, World!"
+    build_docs:
+      parameters:
+        scheduled:
+          type: string
+          default: "false"
+      docker:
+        - image: cimg/base:current-22.04
+      steps:
+        - checkout
+        - run:
+            name: Check-skip
+            command: |
+              set -e
+              export COMMIT_MESSAGE=$(git log --format=oneline -n 1);
+              if [[ -v CIRCLE_PULL_REQUEST ]] && ([[ "$COMMIT_MESSAGE" == *"[skip circle]"* ]] || [[ "$COMMIT_MESSAGE" == *"[circle skip]"* ]]); then
+                echo "Skip detected, exiting job ${CIRCLE_JOB} for PR ${CIRCLE_PULL_REQUEST}."
+                circleci-agent step halt;
+              fi
+        - run:
+            name: Set BASH_ENV
+            command: |
+              set -e
+              set -o pipefail
+              git clone --single-branch --branch main [email protected]:/mne-tools/mne-python.git
+              ./mne-python/tools/setup_xvfb.sh
+              sudo apt install -qq graphviz optipng python3.10-venv python3-venv libxft2 ffmpeg
+              python3.10 -m venv ~/python_env
+              echo "set -e" >> $BASH_ENV
+              echo "export OPENBLAS_NUM_THREADS=4" >> $BASH_ENV
+              echo "export XDG_RUNTIME_DIR=/tmp/runtime-circleci" >> $BASH_ENV
+              echo "export PATH=~/.local/bin/:$PATH" >> $BASH_ENV
+              echo "export DISPLAY=:99" >> $BASH_ENV
+              echo "source ~/python_env/bin/activate" >> $BASH_ENV
+              mkdir -p ~/.local/bin
+              ln -s ~/python_env/bin/python ~/.local/bin/python
+              echo "BASH_ENV:"
+              cat $BASH_ENV
+              mkdir -p ~/mne_data
+        - run:
+            name: Get Python running
+            command: |
+              pip install --upgrade PyQt6 sphinx-gallery pydata-sphinx-theme numpydoc scikit-learn git+https://github.com/pyvista/pyvista@main memory_profiler
+              pip install -ve ./mne-python .
+        - run:
+            name: Check Qt
+            command: |
+              ./mne-python/tools/check_qt_import.sh PyQt6
+        - run:
+            name: Check installation
+            command: |
+               which python
+               QT_DEBUG_PLUGINS=1 mne sys_info -pd
+               python -c "import numpy; numpy.show_config()"
+               LIBGL_DEBUG=verbose python -c "import pyvistaqt; pyvistaqt.BackgroundPlotter(show=True)"
+        - run:
+            name: List packages
+            command: python -m pip list
+        - restore_cache:
+            keys:
+              - data-cache-somato
+        - run:
+            name: Get data
+            command: |
+              python -c "import mne; mne.datasets.somato.data_path(update_path=True, verbose=True)"
+              ls -al ~/mne_data;
+        - run:
+            name: make html
+            command: |
+              make -C doc html
+        - store_test_results:
+            path: doc/_build/test-results
+        - store_artifacts:
+            path: doc/_build/test-results
+            destination: test-results
+        - store_artifacts:
+            path: doc/_build/html/
+            destination: dev
+        - persist_to_workspace:
+            root: doc/_build
+            paths:
+              - html
+        - save_cache:
+            key: data-cache-somato
+            paths:
+              - ~/mne_data/MNE-somato-data
+
+    deploy:
+      machine:
+        image: ubuntu-2004:202111-01
+      steps:
+        - attach_workspace:
+            at: /tmp/build
+        - restore_cache:
+            keys:
+              - website-cache
+        - add_ssh_keys:
+            fingerprints:
+              - "18:ca:dc:af:9a:80:ee:23:91:fd:84:ae:93:7a:7b:4f"
+        - run:
+            name: Deploy docs
+            command: |
+              set -eo pipefail
+              mkdir -p ~/.ssh
+              echo -e "Host *\nStrictHostKeyChecking no" > ~/.ssh/config
+              chmod og= ~/.ssh/config
+              git config --global user.email "[email protected]"
+              git config --global user.name "Circle CI"
+              if [ ! -d ~/mne-tools.github.io ]; then
+                git clone [email protected]:/mne-tools/mne-tools.github.io.git ~/mne-tools.github.io
+              fi
+              cd ~/mne-tools.github.io
+              git checkout main
+              git fetch origin
+              git reset --hard origin/main
+              git clean -xdf
+              echo "Deploying dev docs for ${CIRCLE_BRANCH}."
+              mkdir -p mne-gui-addons
+              rm -Rf mne-gui-addons/dev
+              cp -a /tmp/build/html mne-gui-addons/dev
+              git add -A
+              git commit -m "CircleCI update of mne-gui-addons docs (${CIRCLE_BUILD_NUM})."
+              git push origin main
+        - save_cache:
+            key: website-cache
+            paths:
+              - ~/mne-tools.githbub.io
 
-# Orchestrate jobs using workflows
-# See: https://circleci.com/docs/configuration-reference/#workflows
 workflows:
-  say-hello-workflow:
+  default:
     jobs:
-      - say-hello
+      - build_docs:
+          name: build_docs
+      - deploy:
+          name: deploy
+          requires:
+            - build_docs
+          filters:
+            branches:
+              only:
+                - main

.github/workflows/tests.yml

@@ -20,15 +20,20 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.11"]  # Oldest and newest supported versions
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11"]  # Newest supported version (dipy not out for 3.11 yet!)
         mne-version: [mne-main]
         qt: [PyQt6]
         include:
+          # macOS (can be moved above once Dipy releases 3.11 wheels)
+          - os: macos-latest
+            python-version: "3.10"
+            mne-version: mne-main  # TODO: Set back to mne-stable once 1.4 is out (we need its pytest fixtures)
+            qt: PyQt6
           # Old (and PyQt5)
           - os: ubuntu-latest
             python-version: "3.8"
-            mne-version: mne-stable
+            mne-version: mne-main  # TODO: Set back to mne-stable once 1.4 is out (we need its pytest fixtures)
             qt: PyQt5
           # PySide2
           - os: ubuntu-latest

.gitignore

@@ -130,3 +130,6 @@ dmypy.json
 
 # Other
 junit-results.xml
+doc/_build/
+doc/auto_examples/
+doc/generated/

doc/Makefile

@@ -0,0 +1,43 @@
+SPHINXOPTS    = -nWT --keep-going
+SPHINXBUILD   = sphinx-build
+PAPER         =
+MPROF         = SG_STAMP_STARTS=true mprof run -E --python sphinx
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+# make with no arguments will build the first target by default, i.e., build standalone HTML files
+first_target: html-noplot
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html             to make standalone HTML files (dev version)"
+	@echo "  html-pattern     to make standalone HTML files for one example dir (dev version)"
+	@echo "  *-noplot         to make standalone HTML files without plotting"
+
+clean:
+	-rm -rf _build auto_examples auto_tutorials generated *.stc *.fif *.nii.gz
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+html-pattern:
+	$(SPHINXBUILD) -D sphinx_gallery_conf.filename_pattern=$(PATTERN) -D sphinx_gallery_conf.run_stale_examples=True -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html"
+
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+view:
+	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"
+
+show: view

doc/_templates/autosummary/class.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__
+   :members:
+
+.. _sphx_glr_backreferences_{{ fullname }}:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/_templates/autosummary/function.rst

@@ -0,0 +1,10 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. _sphx_glr_backreferences_{{ fullname }}:
+
+.. minigallery:: {{ fullname }}
+    :add-heading:

doc/api.rst

@@ -0,0 +1,17 @@
+.. _api_reference:
+
+====================
+Python API Reference
+====================
+
+:py:mod:`mne_gui_addons`:
+
+.. automodule:: mne_gui_addons
+    :no-members:
+    :no-inherited-members:
+
+.. autosummary::
+   :toctree: generated/
+
+   locate_ieeg
+   view_vol_stc