ci: Use GH Pages actions to publish the docs

.github/workflows/publish-docs.yml

@@ -1,22 +1,33 @@
 name: Publish Docs
 
 on:
+  # Runs whenever there is a release/tag creation
   push:
     tags:
-      # Only runs for version tags:
-      # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#running-your-workflow-only-when-a-push-of-specific-tags-occurs
       - '[0-9]+.[0-9]+.[0-9]+'
 
+permissions:
+  # Checkout the project's code
+  contents: read
+  # Allow to deploy to gh-pages
+  pages: write
+  # To verify the deployment originates from an appropriate source
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
-  deploy:
-    permissions:
-      contents: write
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           # Fetch all history for all tags and branches.
-          # This is neccessary to later commit on `gh-pages` branches.
+          # This is necessary to later commit on `gh-pages` branches.
           # https://github.com/actions/checkout#Fetch-all-history-for-all-tags-and-branches
           fetch-depth: 0
       - uses: actions/setup-python@v4
@@ -39,7 +50,27 @@ jobs:
         run: |
           git config user.email "$(git log --format='%ae' HEAD -1)"
           git config user.name "$(git log --format='%an' HEAD -1)"
-      - name: Publish new page
+      - name: Create new docs version
+        # We would still have a GitHub Pages branch to store the versions.
+        # `mike deploy --push` creates a commit in the gh-pages branch and
+        # automatically pushes it to the remote.
         run: mike deploy --push --update-aliases "${{ github.ref_name }}" latest
-      - name: Latest version as the default
-        run: mike set-default --push latest
+      - name: Checkout gh-pages branch
+        run: git checkout gh-pages
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2