Set up multi-version docs (#633)

* adapt conf.py and docs CI worflow for multi-version docs

* Update install and get_started links in README

* use the stabler v2 version of docs actions

---------

Co-authored-by: JoeZiminski <joseph.j.ziminski@gmail.com>

Author: niksirbi

.github/workflows/docs_build_and_deploy.yml

@@ -24,7 +24,7 @@ jobs:
     name: Build Sphinx Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: neuroinformatics-unit/actions/build_sphinx_docs@main
+      - uses: neuroinformatics-unit/actions/build_sphinx_docs@v2
         with:
           use-artifactci: lazy
 
@@ -33,9 +33,14 @@ jobs:
     needs: build_sphinx_docs
     permissions:
       contents: write
-    if: github.event_name == 'push' && github.ref_type == 'tag'
+    # runs on releases, push to main, or manual dispatch on main
+    if: |
+      (github.event_name == 'push' && github.ref_type == 'tag') ||
+      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
     runs-on: ubuntu-latest
     steps:
-      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@v2
+      - uses: neuroinformatics-unit/actions/deploy_sphinx_docs_multiversion@v2
         with:
           secret_input: ${{ secrets.GITHUB_TOKEN }}
+          switcher-url: https://datashuttle.neuroinformatics.dev/latest/_static/switcher.json

README.md

@@ -2,9 +2,9 @@
 
 **datashuttle** is a tool to automate creation, validation and transfer of neuroscience project folders.
 
-Learn how to [Install](https://datashuttle.neuroinformatics.dev/pages/get_started/install.html)
+Learn how to [Install](https://datashuttle.neuroinformatics.dev/latest/pages/get_started/install.html)
 and
-[Get Started](https://datashuttle.neuroinformatics.dev/pages/get_started/index.html)
+[Get Started](https://datashuttle.neuroinformatics.dev/latest/pages/get_started/index.html)
 on the
 [**datashuttle** website](https://datashuttle.neuroinformatics.dev).
 

docs/source/conf.py

@@ -23,12 +23,14 @@
 # Retrieve the version number from the package
 try:
     release = setuptools_scm.get_version(root="../..", relative_to=__file__)
-    release = release.split(".dev")[0]  # remove dev tag and git hash
+    release = release.split("+")[0]  # remove git hash
 except LookupError:
     # if git is not initialised, still allow local build
     # with a dummy version
     release = "0.0.0"
 
+doc_version = "dev" if "dev" in release else f"v{release}"
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -148,6 +150,11 @@
             "type": "fontawesome",
         },
     ],
+    "switcher": {
+        "json_url": "https://datashuttle.neuroinformatics.dev/latest/_static/switcher.json",
+        "version_match": doc_version,
+    },
+    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
     "logo": {
         "text": f"datashuttle v{release}",
         "image_light": "_static/logo_light.png",