Docs site versions

.github/workflows/docs.yml

@@ -1,22 +1,81 @@
 name: docs
 on:
   workflow_dispatch:
+  release:
+    types:
+      - published
   push:
     branches:
       - main
     paths:
       - "docs/**"
-      - mkdocs.yml
+      - "**.md"
       - .github/workflows/docs.yml
+      - mkdocs.yml
+
+env:
+  actor: "41898282+github-actions[bot]"
+  GH_TOKEN: ${{ github.token }}
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.11
-      - run: pip install --upgrade pip
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --force
+          cache: pip
+      - run: pip install --upgrade pip -r docs/requirements.txt
+      - name: git config
+        run: |
+          git config --local user.email "${actor}@users.noreply.github.com"
+          git config --local user.name "$actor"
+          gh release list > releases.tsv
+      - name: get version tag & alias
+        shell: python {0}
+        run: |
+          import os
+          import re
+          import warnings
+
+          release_tag = ''
+          with open('releases.tsv', 'r') as infile:
+            for line in infile:
+              release_name, latest, tag, timestamp = line.strip().split('\t')
+              if latest == "Latest":
+                release_tag = tag.strip('v')
+                break
+          if not release_tag:
+            warnings.warn("No latest release found")
+
+          with open('VERSION', 'r') as infile:
+            current_version = infile.read().strip()
+
+          if current_version == release_tag:
+            docs_alias = 'latest'
+            docs_version = release_tag
+          else:
+            semver_pattern = '(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?'
+            release_semver = re.match(semver_pattern, release_tag)
+            current_semver = re.match(semver_pattern, current_version)
+
+            groups = ['major', 'minor', 'patch']
+            if current_semver.group('prerelease') and any([current_semver.group(grp) >= release_semver.group(grp) for grp in groups]):
+              docs_alias = ''
+              docs_version = 'dev'
+            else:
+              raise ValueError(f"current version {current_version} is not greater than latest release {release_tag}")
+
+          with open(os.getenv("GITHUB_ENV"), 'a') as out_env:
+            out_env.write(f"VERSION={docs_version}\n")
+            out_env.write(f"ALIAS={docs_alias}\n")
+
+      - name: deploy docs
+        run: |
+          mike deploy ${{ env.VERSION }} ${{ env.ALIAS }} \
+            --push \
+            --update-aliases \
+            --branch gh-pages

CHANGELOG.md

@@ -3,6 +3,7 @@
 - You can now cite XAVIER with the DOI [10.5281/zenodo.12727315](https://doi.org/10.5281/zenodo.12727315). (#88, @kelly-sovacool)
 - Minor documentation improvements. (#92, @kelly-sovacool)
 - Minor documentation rendering improvements (#93, @samarth8392)
+- The docs website now has a dropdown menu to select which version to view. The latest release is shown by default. (#150, @kelly-sovacool)
 
 ## XAVIER 3.0.3
 

mkdocs.yml

@@ -46,6 +46,10 @@ plugins:
   - git-revision-date
   - minify:
       minify_html: true
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
+      version_selector: true
 
 # Customization
 extra:
@@ -74,8 +78,8 @@ markdown_extensions:
   - pymdownx.critic
   - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.highlight
   - pymdownx.inlinehilite
   - pymdownx.keys