Separate stable and dev documentation deployments with version switcher

.github/workflows/docs.yml

@@ -181,6 +181,8 @@ jobs:
           # Disable parallel builds when cache is cold to avoid Zenodo rate limiting
           SPHINX_GALLERY_PARALLEL: ${{ steps.cache-mne_data.outputs.cache-matched-key != '' }}
           SPHINX_JOBS: ${{ steps.cache-mne_data.outputs.cache-matched-key != '' && 'auto' || '1' }}
+          # Signal whether this is a dev (develop branch) or stable (master) build
+          BUILD_DEV_HTML: ${{ github.ref == 'refs/heads/develop' && '1' || '0' }}
         run: |
           echo "Cache hit: ${{ steps.cache-mne_data.outputs.cache-hit }}"
           echo "Cache matched key: ${{ steps.cache-mne_data.outputs.cache-matched-key }}"
@@ -220,7 +222,7 @@ jobs:
           name: DocumentationHTML
           path: docs/build/html/
 
-  deploy_neurotechx:
+  deploy_neurotechx_dev:
     if: ${{ github.ref == 'refs/heads/develop' }}
     needs: build_docs
     runs-on: ${{ matrix.os }}
@@ -243,7 +245,41 @@ jobs:
         if: steps.cache-docs.outputs.cache-hit != 'true'
         run: exit 1
 
-      - name: Deploy Neurotechx Subpage
+      - name: Deploy Neurotechx Dev Subpage
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+          external_repository: NeuroTechX/moabb.github.io
+          destination_dir: docs/dev/
+          publish_branch: master
+          publish_dir: ./docs/build/html
+          cname: moabb.neurotechx.com/
+
+  deploy_neurotechx_stable:
+    if: ${{ github.ref == 'refs/heads/master' }}
+    needs: build_docs
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore cached docs build
+        id: cache-docs
+        uses: actions/cache/restore@v3
+        with:
+          key: docs-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: docs/build
+
+      - name: Check cache hit
+        if: steps.cache-docs.outputs.cache-hit != 'true'
+        run: exit 1
+
+      - name: Deploy Neurotechx Stable Subpage
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -254,7 +290,7 @@ jobs:
           publish_dir: ./docs/build/html
           cname: moabb.neurotechx.com/
 
-  deploy_gh_pages:
+  deploy_gh_pages_dev:
     if: ${{ github.ref == 'refs/heads/develop' }}
     needs: build_docs
     runs-on: ${{ matrix.os }}
@@ -277,12 +313,43 @@ jobs:
         if: steps.cache-docs.outputs.cache-hit != 'true'
         run: exit 1
 
-      - name: Deploy gh-pages
+      - name: Deploy gh-pages dev
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          deploy_key: ${{ secrets.MOABB_DEPLOY_KEY_NEW }}
+          destination_dir: docs/dev/
+          publish_branch: gh-pages
+          publish_dir: ./docs/build/html
+
+  deploy_gh_pages_stable:
+    if: ${{ github.ref == 'refs/heads/master' }}
+    needs: build_docs
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore cached docs build
+        id: cache-docs
+        uses: actions/cache/restore@v3
+        with:
+          key: docs-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: docs/build
+
+      - name: Check cache hit
+        if: steps.cache-docs.outputs.cache-hit != 'true'
+        run: exit 1
+
+      - name: Deploy gh-pages stable
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           deploy_key: ${{ secrets.MOABB_DEPLOY_KEY_NEW }}
           destination_dir: docs/
           publish_branch: gh-pages
           publish_dir: ./docs/build/html
-          cname: neurotechx.github.io/moabb/

docs/source/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+    {
+        "name": "stable",
+        "version": "stable",
+        "url": "https://moabb.neurotechx.com/docs/"
+    },
+    {
+        "name": "dev",
+        "version": "dev",
+        "url": "https://moabb.neurotechx.com/docs/dev/"
+    }
+]

docs/source/conf.py

@@ -45,10 +45,13 @@
 copyright = f"2018-{year} MOABB contributors"
 author = "Alexandre Barachant, Vinay Jayaram, Sylvain Chevallier"
 
+# Check if this is a dev/nightly build (set to "1" by CI on the develop branch)
+_is_dev_build = bool(int(os.environ.get("BUILD_DEV_HTML", "0")))
+
 # The short X.Y version
 version = moabb.__version__
 # The full version, including alpha/beta/rc tags
-release = f"{moabb.__version__}-dev"
+release = f"{version}.dev0" if _is_dev_build else version
 
 # Control the page title suffix in <title> tags for SEO
 html_title = "MOABB Documentation"
@@ -173,7 +176,8 @@ def linkcode_resolve(domain, info):  # noqa: C901
     #     kind = "develop"
     # else:
     #     kind = "master"
-    return f"{repo}/blob/develop/moabb/{fn}{linespec}"
+    kind = "develop" if _is_dev_build else "master"
+    return f"{repo}/blob/{kind}/moabb/{fn}{linespec}"
 
 
 # -- Path setup --------------------------------------------------------------
@@ -246,7 +250,7 @@ def linkcode_resolve(domain, info):  # noqa: C901
 
 
 html_theme = "pydata_sphinx_theme"
-switcher_version_match = "dev" if release.endswith("dev0") else version
+switcher_version_match = "dev" if _is_dev_build else "stable"
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -271,7 +275,11 @@ def linkcode_resolve(domain, info):  # noqa: C901
     "navigation_depth": -1,
     "show_toc_level": 1,
     "nosidebar": True,
-    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "switcher": {
+        "json_url": "https://moabb.neurotechx.com/docs/switcher.json",
+        "version_match": switcher_version_match,
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "announcement": (
         "<strong>Using MOABB in academic work?</strong> "
         "<a class='moabb-announcement-cta' href='cite.html'>Cite MOABB</a> "
@@ -316,7 +324,11 @@ def linkcode_resolve(domain, info):  # noqa: C901
 html_static_path = ["_static"]
 
 # Base URL for sitemap generation (required by sphinx_sitemap)
-html_baseurl = "https://moabb.neurotechx.com/docs/"
+html_baseurl = (
+    "https://moabb.neurotechx.com/docs/dev/"
+    if _is_dev_build
+    else "https://moabb.neurotechx.com/docs/"
+)
 
 # Sitemap configuration
 sitemap_url_scheme = "{link}"
@@ -412,7 +424,7 @@ def linkcode_resolve(domain, info):  # noqa: C901
     "show_toc_level": 1,
     "github_user": "neurotechx",
     "github_repo": "moabb",
-    "github_version": "develop",
+    "github_version": "develop" if _is_dev_build else "master",
     "doc_path": "docs",
     # Colab launcher for Sphinx-Gallery examples (see _templates/sg_launcher_links.html)
     "colab_repo": "NeuroTechX/moabb",

docs/source/whats_new.rst

@@ -23,6 +23,7 @@ Version 1.6  (Source - GitHub)
 
 Enhancements
 ~~~~~~~~~~~~
+- Separate stable and development documentation: stable docs now deploy from ``master`` to ``moabb.neurotechx.com/docs/`` and dev docs deploy from ``develop`` to ``moabb.neurotechx.com/docs/dev/``. A version switcher is added to the navbar (:gh:`984` by `Bruno Aristimunha`_)
 - Add :class:`moabb.datasets.Lenaig2026` - SSAEP-BCI data of 48 participants in response to a set of four auditory stimuli: a pure tone (used as a reference), cicada song and cat's purr, and brownian noise. EEG acquisition is performed using a 24-channel (international 10-20 system, passive electrodes, impedance maintained below 10 kΩ) at a sampling rate of 500 Hz. The stimuli are amplitude-modulated by a 40 Hz sinusoid and have a duration of 10 seconds. The experiment is conducted at two loudness levels (60 and 66 phons, diotic presentation), with 24 participants each. The measurement consists in one session of two 10-minute runs (separated by a 5-minute break), each including 50 trials (10 repetitions per condition). (:gh:`1121` by `Henrique Lefundes`_)
 - Add :class:`moabb.datasets.Schrag2026Pediatric` — open-access pediatric SSVEP-BCI dataset (47 children aged 5-18, g.tec g.GAMMAsys + g.USBamp at 256 Hz, 16 channels) covering both an online 4-target SSVEP game (6.25 / 10 / 11.11 / 14.28 Hz) and an opt-in 12-stimulus personalization recording (4 contrasts x 3 sizes at 10 Hz). XDF + Unity markers; trial labels are derived from the matching ``Movements/`` CSV (live fbCCA classifier output). Single 1.2 GB zip on Zenodo (``10.5281/zenodo.19440997``) extracted per-subject on first use; the SSVEP game is exposed as two runs (standard and personal stimulus) of a single session (by `Bruno Aristimunha`_ and `Emily Schrag`_)
 - Add 7 new imagined speech dataset adapters: :class:`moabb.datasets.AguileraRodriguez2025` (15 subjects, 4 Spanish words, traditional vs gamified paradigm), :class:`moabb.datasets.Nguyen2017_V`, :class:`moabb.datasets.Nguyen2017_S`, :class:`moabb.datasets.Nguyen2017_L`, and :class:`moabb.datasets.Nguyen2017_SL` (Nguyen et al. 2017 vowels / short words / long words / short-vs-long conditions), :class:`moabb.datasets.Nieto2022` (10 subjects, 4 directional tasks across inner / pronounced / visualized speech modalities, 128-ch BioSemi), and :class:`moabb.datasets.Pressel2016` (15 subjects, 11-class Spanish vowels and directional commands) (by `Bruno Aristimunha`_)