ci: update deployment process for the documentation (#205)

* ci: update deployment process of documentation

Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>

* fix: update mkdocs config for better version selector

Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>

* Update .github/workflows/deploy-document.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: fix pre-commit

Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>

---------

Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ktro2828

.github/workflows/deploy-document.yaml

@@ -8,14 +8,17 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to deploy (e.g., v1.0.0, latest, dev)"
+        description: "Version to deploy (e.g., v1.0.0, latest, develop)"
         required: true
-        default: "latest"
+        default: "develop"
       alias:
         description: "Version alias (e.g., latest, stable)"
         required: false
         default: ""
 
+permissions:
+  contents: write # Required for mike to push to gh-pages branch
+
 jobs:
   deploy-document:
     runs-on: ubuntu-latest
@@ -45,27 +48,36 @@ jobs:
             VERSION="${{ github.event.inputs.version }}"
             ALIAS="${{ github.event.inputs.alias }}"
           elif [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            # For version tags (e.g., v1.0.0), use the tag name and set latest alias
             VERSION="${{ github.ref_name }}"
             ALIAS="latest"
           else
+            # For main branch pushes (non-tag), deploy as develop
             VERSION="develop"
             ALIAS=""
           fi
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "alias=$ALIAS" >> $GITHUB_OUTPUT
-          echo "Deploying version: $VERSION"
 
       - name: Deploy documentation
         run: |
           VERSION="${{ steps.version.outputs.version }}"
           ALIAS="${{ steps.version.outputs.alias }}"
 
           if [[ -n "$ALIAS" ]]; then
+            echo "Deploying documentation for version: $VERSION with alias: $ALIAS"
             uv run mike deploy --push --update-aliases $VERSION $ALIAS
             uv run mike set-default --push $ALIAS
           else
+            echo "Deploying documentation for version: $VERSION (no alias set)"
             uv run mike deploy --push $VERSION
           fi
+        env:
+          # Ensure GitHub Pages deployment works correctly
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: List versions
-        run: uv run mike list
+      - name: List deployed versions
+        run: |
+          echo "Currently deployed versions:"
+          uv run mike list
+          echo "Documentation deployment completed successfully!"

mkdocs.yaml

@@ -50,6 +50,7 @@ plugins:
   - search
   - mike:
       version_selector: true
+      canonical_version: latest
   - mkdocstrings:
       handlers:
         python: