feat: add BrainX shared header integration for documentation

Author: chaoming0625

.github/workflows/deploy-docs.yml

@@ -43,6 +43,7 @@ jobs:
       - name: Build documentation
         run: |
           sphinx-build -b html docs docs/_build/html
+          test -f docs/_build/html/index.html
 
       - name: Upload documentation artifact
         uses: actions/upload-artifact@v7
@@ -51,29 +52,56 @@ jobs:
           path: docs/_build/html/
           if-no-files-found: error
 
-      - name: Clean remote target
+      - name: Create release id
+        id: release
+        run: echo "id=$(date -u +%Y%m%d%H%M%S)-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
+
+      - name: Prepare remote release
         uses: appleboy/ssh-action@v1.2.0
         with:
           host:     ${{ secrets.DEPLOY_HOST }}
           port:     ${{ secrets.DEPLOY_PORT }}
           username: ${{ secrets.DEPLOY_USER }}
           key:      ${{ secrets.DEPLOY_SSH_KEY }}
           script: |
-            mkdir -p ${{ secrets.DEPLOY_PATH }}
-            find ${{ secrets.DEPLOY_PATH }} -mindepth 1 -delete
+            set -e
+            base="${{ secrets.DEPLOY_PATH }}"
+            release="$base/releases/${{ steps.release.outputs.id }}"
+            mkdir -p "$base/releases"
+            rm -rf "$release"
+            mkdir -p "$release"
 
-      - name: Upload docs via SCP
+      - name: Upload docs to release
         uses: appleboy/scp-action@v0.1.7
         with:
           host:     ${{ secrets.DEPLOY_HOST }}
           port:     ${{ secrets.DEPLOY_PORT }}
           username: ${{ secrets.DEPLOY_USER }}
           key:      ${{ secrets.DEPLOY_SSH_KEY }}
           source:   "docs/_build/html/*"
-          target:   ${{ secrets.DEPLOY_PATH }}
+          target:   ${{ secrets.DEPLOY_PATH }}/releases/${{ steps.release.outputs.id }}
           strip_components: 3
 
-      - name: Reload nginx
+      - name: Activate release
+        uses: appleboy/ssh-action@v1.2.0
+        with:
+          host:     ${{ secrets.DEPLOY_HOST }}
+          port:     ${{ secrets.DEPLOY_PORT }}
+          username: ${{ secrets.DEPLOY_USER }}
+          key:      ${{ secrets.DEPLOY_SSH_KEY }}
+          script: |
+            set -e
+            base="${{ secrets.DEPLOY_PATH }}"
+            release="$base/releases/${{ steps.release.outputs.id }}"
+            test -f "$release/index.html"
+            ln -sfn "$release" "$base/current.next"
+            mv -Tf "$base/current.next" "$base/current"
+            current="$(readlink -f "$base/current")"
+            find "$base/releases" -mindepth 1 -maxdepth 1 -type d \
+              ! -samefile "$current" \
+              -exec rm -rf {} +
+
+      - name: Reload nginx (optional)
         uses: appleboy/ssh-action@v1.2.0
         with:
           host:     ${{ secrets.DEPLOY_HOST }}