Docs versioning (#3138)

* Docs versioning

* Fix Lint issues

* Fix lint

* CR changes

* CR changes

* CR changes

* Fix lint

* Fix lint

* Fix lint

* Cr changes

.github/workflows/build_docs.yml

@@ -1,21 +1,39 @@
 ---
-name: Publish docs via Github Pages
-
-on:  # yamllint disable-line rule:truthy
+name: Deploy Documentation
+on:
   workflow_dispatch:
+  release:
+    types: [published]
   push:
-    branches: [main]
     paths:
       - 'docs/**'
-
+      - mkdocs.yml
+    branches:
+      - main
 jobs:
-  build:
-    name: Deploy docs
+  deploy:
+    name: Deploy Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout main
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          persist-credentials: true
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --strict --force
+      - name: Install Dependencies
+        run: |
+          pip install -r docs/requirements.txt
+      - name: Configure Git User
+      # Required by mike for the commit it does to the gh-pages branch
+        run: |
+          git config user.name "ci-docs"
+          git config user.email "ci-docs@dummy.com"
+      - name: Deploy the latest documents from new release
+        if: ${{ github.event_name == 'release' }}
+        run: mike deploy --push --update-aliases "${GITHUB_REF#refs/*/}" latest-release
+      - name: Deploy the development docs
+        if: ${{ github.event_name != 'release' }}
+        run: mike deploy --push develop

docs/requirements.txt

@@ -4,3 +4,4 @@ mkdocs
 mkdocs-material
 mkdocs-material-extensions
 mkdocstrings
+mike

mkdocs-overrides/main.html

@@ -1,5 +1,13 @@
 {% extends "base.html" %}
 
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+</script>
+{% endblock %}
+
 {% block analytics %}
 <script type="text/javascript">
   (function(c,l,a,r,i,t,y){

mkdocs.yml

@@ -22,6 +22,10 @@ theme:
   features:
     - navigation.instant
     - navigation.indexes
+extra:
+  version:
+    provider: mike
+    default: latest-release
 
 plugins:
   - search