diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b7d00d3fd..548ad5e03 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -161,6 +161,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 matched key: ${{ steps.cache-mne_data.outputs.cache-matched-key }}" echo "Parallel gallery builds: $SPHINX_GALLERY_PARALLEL" @@ -199,7 +201,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 }} @@ -222,7 +224,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 }} @@ -233,7 +269,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 }} @@ -256,7 +292,39 @@ 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 }} @@ -264,4 +332,3 @@ jobs: destination_dir: docs/ publish_branch: gh-pages publish_dir: ./docs/build/html - cname: neurotechx.github.io/moabb/ diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json new file mode 100644 index 000000000..3e46a6b00 --- /dev/null +++ b/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/" + } +] diff --git a/docs/source/conf.py b/docs/source/conf.py index 742f3d80e..425656d56 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -32,10 +32,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 # -- General configuration --------------------------------------------------- @@ -148,7 +151,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 -------------------------------------------------------------- @@ -221,7 +225,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. @@ -246,7 +250,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": ( "Using MOABB in academic work? " "Cite MOABB " @@ -291,7 +299,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}" @@ -333,7 +345,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", diff --git a/docs/source/whats_new.rst b/docs/source/whats_new.rst index cdad439d8..431da18a6 100644 --- a/docs/source/whats_new.rst +++ b/docs/source/whats_new.rst @@ -19,6 +19,7 @@ Version 1.5 (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`_) - Implementation of Pseudo-Online framework (:gh:`641` by `Igor Carrara`_ and `Bruno Aristimunha`_) - Introduce a new logo for the MOABB library (:gh:`858` by `Pierre Guetschel`_ and community) - Better verbosity control for initialization of the library (:gh:`850` by `Bruno Aristimunha`_)