Merge pull request #150 from CCBR/docs-site-versions

docs: use mike for multiple docs versions on website

.github/workflows/docs.yml

@@ -1,6 +1,9 @@
-name: mkdocs
+name: docs
 on:
   workflow_dispatch:
+  release:
+    types:
+      - published
   push:
     branches:
       - main
@@ -12,19 +15,67 @@ on:
 
 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:
-          python-version: 3.9
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          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"
-      - run: pip install --upgrade pip
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --force
+          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

@@ -5,6 +5,7 @@
 - Show the name of the pipeline rather than the python script for CLI help messages. (#131, @kelly-sovacool)
 - Add GUI instructions to the documentation website. (#38, @samarth8392)
 - Ensure `renee build` creates necessary `config` directory during initialization. (#139, @kelly-sovacool)
+- The docs website now has a dropdown menu to select which version to view. The latest release is shown by default. (#150, @kelly-sovacool)
 
 ## RENEE 2.5.12
 

docs/requirements.txt

@@ -1,34 +1,13 @@
-Babel==2.8.0
-click==7.1.2
-future==0.18.2
-gitdb==4.0.5
-GitPython==3.1.7
-htmlmin==0.1.12
-importlib-metadata==1.7.0
-Jinja2==2.11.2
-joblib==0.16.0
-jsmin==3.0.0
-livereload==2.6.1
-lunr==0.5.8
-Markdown==3.2.2
-MarkupSafe==1.1.1
-mkdocs==1.1.2
-mkdocs-awesome-pages-plugin==2.2.1
-mkdocs-git-revision-date-localized-plugin==0.7
+mkdocs
+#https://pypi.org/project/mkdocs-git-revision-date-localized-plugin/
+mkdocs-git-revision-date-localized-plugin
+#https://pypi.org/project/mkdocs-minify-plugin/
+mkdocs-minify-plugin
+#https://pypi.org/project/mkdocs-git-revision-date-plugin/
+mkdocs-git-revision-date-plugin
+#https://pypi.org/project/mkdocs-material/
 mkdocs-material
+#https://pypi.org/project/mkdocs-material-extensions/
 mkdocs-material-extensions
-mkdocs-minify-plugin==0.3.0
-mkdocs-redirects==1.0.1
-nltk==3.5
-Pygments==2.6.1
-pymdown-extensions==7.1
-pytz==2020.1
-PyYAML==5.3.1
-regex==2020.7.14
-six==1.15.0
-smmap==3.0.4
-tornado==6.0.4
-tqdm==4.48.2
-zipp==3.1.0
-mkdocs-git-revision-date-plugin
+#https://github.com/jimporter/mike
 mike

mkdocs.yml

@@ -42,6 +42,10 @@ plugins:
   - git-revision-date
   - minify:
       minify_html: true
+  - mike:
+      alias_type: symlink
+      canonical_version: latest
+      version_selector: true
 
 # Customization
 extra: