ci: Refactor documentation deployment workflow for GitHub Pages

This commit updates the documentation deployment workflow (`docs.yml`) to align with current best practices for deploying to GitHub Pages.

- **Permissions:** Added `pages: write` and `id-token: write` permissions, which are required for modern GitHub Pages deployments.
- **Git Configuration:** Added a step to configure the Git user name and email for the `github-actions[bot]`.
- **Deployment Steps:** The deployment process has been split into two distinct steps:
    1.  `mkdocs build --strict`: Builds the MkDocs site. The `--strict` flag ensures the build fails on any warnings.
    2.  `mkdocs gh-deploy --force --clean --verbose`: Deploys the built site to GitHub Pages, cleaning the target branch before deployment and providing verbose output.

Author: hi-manshu

.github/workflows/docs.yml

@@ -10,6 +10,8 @@ on:
 
 permissions:
   contents: write
+  pages: write
+  id-token: write
 
 jobs:
   deploy:
@@ -20,6 +22,11 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -37,6 +44,10 @@ jobs:
         run: |
           pip install -r requirements.txt
 
-      - name: Build and deploy MkDocs to GitHub Pages
+      - name: Build MkDocs site
+        run: |
+          mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
         run: |
-          mkdocs gh-deploy --force
+          mkdocs gh-deploy --force --clean --verbose