fix: run documentation deployment in parallel with tests

.github/workflows/docs.yml

@@ -1,15 +1,15 @@
-name: Documentation
+name: Documentation (Manual)
 
-# Auto-generate and publish API documentation and Interactive Playground
-# Triggered after Build & SonarCloud completes to reuse build artifacts
+# Manual-only documentation rebuild and deployment
+# NOTE: Automatic deployment happens in Build & SonarCloud workflow on master pushes
+# This workflow is for manual rebuilds when needed (e.g., fixing doc content without code changes)
 on:
-  workflow_run:
-    workflows: ["Build & SonarCloud"]
-    types:
-      - completed
-    branches:
-      - master
   workflow_dispatch:
+    inputs:
+      skip_playground:
+        description: 'Skip Playground build (faster for doc-only changes)'
+        type: boolean
+        default: false
 
 concurrency:
   group: "pages"
@@ -19,7 +19,6 @@ permissions:
   contents: read
   pages: write
   id-token: write
-  actions: read  # Required to download artifacts from other workflows
 
 env:
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
@@ -29,90 +28,88 @@ jobs:
   build-docs:
     name: Build Documentation and Playground
     runs-on: ubuntu-latest
-    # Only run if the triggering workflow succeeded (or if manually dispatched)
-    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4
+      with:
+        fetch-depth: 0
 
     - name: Setup .NET 10.0
-      uses: actions/setup-dotnet@v4
+      uses: actions/setup-dotnet@baa11fbfe1d6520db94683bd5c7a3818018e4309 # v5
       with:
         dotnet-version: '10.0.x'
 
+    - name: Cache NuGet packages
+      uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v4
+      with:
+        path: ~/.nuget/packages
+        key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj', '**/Directory.Build.props') }}
+        restore-keys: |
+          nuget-${{ runner.os }}-
+
     - name: Install DocFX
       run: dotnet tool install --global docfx || true
 
-    - name: Download build artifacts from Build workflow
-      if: github.event_name == 'workflow_run'
-      continue-on-error: true
-      uses: dawidd6/action-download-artifact@v6
-      with:
-        workflow: Build & SonarCloud
-        workflow_conclusion: success
-        name: build-output-${{ github.event.workflow_run.head_sha || github.sha }}
-        path: .
-        if_no_artifact_found: warn
-
-    - name: Restore dependencies and build (fallback if no artifacts)
+    - name: Restore and build
       run: |
-        # Check if build artifacts exist, if not do a fresh build
-        if [ ! -d "src/bin/Release" ]; then
-          echo "No build artifacts found, performing fresh build..."
-          dotnet restore
-          dotnet build -c Release --no-restore -p:TreatWarningsAsErrors=false
-        else
-          echo "Using build artifacts from Build & SonarCloud workflow"
-          # Still need to restore for DocFX metadata extraction
-          dotnet restore
-        fi
+        dotnet restore
+        dotnet build -c Release --no-restore -p:TreatWarningsAsErrors=false
 
     - name: Build DocFX documentation
       run: docfx docfx.json
+      continue-on-error: true  # Don't fail deployment due to docfx warnings
 
     - name: Restore Playground dependencies
+      if: ${{ inputs.skip_playground != true }}
       run: dotnet restore src/AiDotNet.Playground/AiDotNet.Playground.csproj
 
     - name: Build Blazor WASM Playground
+      if: ${{ inputs.skip_playground != true }}
       run: dotnet publish src/AiDotNet.Playground/AiDotNet.Playground.csproj -c Release -o _playground
 
     - name: Copy Playground to documentation site
+      if: ${{ inputs.skip_playground != true }}
       run: |
         mkdir -p _site/playground
         cp -r _playground/wwwroot/* _site/playground/
         # Update base href for the playground subdirectory
         sed -i 's|<base href="/" />|<base href="/AiDotNet/playground/" />|g' _site/playground/index.html
 
-    # Note: DocFX generates the landing page from docs/index.md
-    # The full documentation site includes: Getting Started, Tutorials, Reference, API, and Community sections
-    # Navigation is configured via toc.yml files
-
     - name: Setup Pages
-      uses: actions/configure-pages@v5
+      uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
 
     - name: Upload Pages artifact
-      uses: actions/upload-pages-artifact@v3
+      uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
       with:
         path: _site/
 
     - name: Documentation summary
       run: |
         echo "## Documentation Build Results" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
-        echo "✅ Documentation and Playground built successfully" >> $GITHUB_STEP_SUMMARY
+        echo "Documentation built successfully" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ inputs.skip_playground }}" == "true" ]; then
+          echo "(Playground build was skipped)" >> $GITHUB_STEP_SUMMARY
+        fi
+        if [ "${{ github.ref }}" != "refs/heads/master" ]; then
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Note:** Deployment will be skipped because this workflow was triggered from branch '${{ github.ref_name }}', not 'master'." >> $GITHUB_STEP_SUMMARY
+        fi
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### Links" >> $GITHUB_STEP_SUMMARY
-        echo "- [Documentation Home](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/)" >> $GITHUB_STEP_SUMMARY
-        echo "- [API Reference](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/api/)" >> $GITHUB_STEP_SUMMARY
-        echo "- [Interactive Playground](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/playground/)" >> $GITHUB_STEP_SUMMARY
+        echo "- [Documentation Home](https://ooples.github.io/AiDotNet/)" >> $GITHUB_STEP_SUMMARY
+        echo "- [API Reference](https://ooples.github.io/AiDotNet/api/)" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ inputs.skip_playground }}" != "true" ]; then
+          echo "- [Interactive Playground](https://ooples.github.io/AiDotNet/playground/)" >> $GITHUB_STEP_SUMMARY
+        fi
 
   deploy:
     name: Deploy to GitHub Pages
     runs-on: ubuntu-latest
     needs: build-docs
     # Only deploy from master branch
-    if: (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') || (github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'master')
+    if: github.ref == 'refs/heads/master'
 
     environment:
       name: github-pages
@@ -121,4 +118,4 @@ jobs:
     steps:
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v4
+      uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/sonarcloud.yml

@@ -532,3 +532,104 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Artifacts" >> $GITHUB_STEP_SUMMARY
           echo "- Publish size: ${{ steps.size.outputs.current_mb }} MB" >> $GITHUB_STEP_SUMMARY
+
+  # Documentation build and deployment - runs in parallel with tests after build completes
+  # Deploys DocFX API docs and Blazor WASM Playground to GitHub Pages
+  build-docs:
+    name: Build & Deploy Documentation
+    runs-on: ubuntu-latest
+    needs: build-windows
+    timeout-minutes: 30
+    # Only deploy on master branch pushes (not PRs)
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+
+    # Required permissions for GitHub Pages deployment
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    # Ensure only one pages deployment at a time
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET 10.0
+        uses: actions/setup-dotnet@baa11fbfe1d6520db94683bd5c7a3818018e4309 # v5
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Cache NuGet packages
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v4
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj', '**/Directory.Build.props') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
+
+      - name: Install DocFX
+        run: dotnet tool install --global docfx || true
+
+      # Note: We don't download build artifacts from build-windows because:
+      # 1. DocFX builds from source during metadata extraction
+      # 2. Windows build artifacts may have path incompatibilities on Ubuntu
+      # 3. Playground publish also builds from source
+      - name: Restore and build
+        run: |
+          dotnet restore
+          dotnet build -c Release --no-restore -p:TreatWarningsAsErrors=false
+
+      - name: Build DocFX documentation
+        run: docfx docfx.json
+        continue-on-error: true  # Don't fail deployment due to docfx warnings
+
+      - name: Restore Playground dependencies
+        run: dotnet restore src/AiDotNet.Playground/AiDotNet.Playground.csproj
+
+      - name: Build Blazor WASM Playground
+        run: dotnet publish src/AiDotNet.Playground/AiDotNet.Playground.csproj -c Release -o _playground
+
+      - name: Copy Playground to documentation site
+        run: |
+          mkdir -p _site/playground
+          cp -r _playground/wwwroot/* _site/playground/
+          # Update base href for the playground subdirectory
+          sed -i 's|<base href="/" />|<base href="/AiDotNet/playground/" />|g' _site/playground/index.html
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: _site/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
+
+      - name: Documentation summary
+        if: always()
+        run: |
+          echo "## Documentation Build Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ steps.deployment.outcome }}" == "success" ]; then
+            echo "Documentation and Playground deployed successfully" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "Documentation build completed (deployment may have warnings)" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Links" >> $GITHUB_STEP_SUMMARY
+          echo "- [Documentation Home](https://ooples.github.io/AiDotNet/)" >> $GITHUB_STEP_SUMMARY
+          echo "- [API Reference](https://ooples.github.io/AiDotNet/api/)" >> $GITHUB_STEP_SUMMARY
+          echo "- [Interactive Playground](https://ooples.github.io/AiDotNet/playground/)" >> $GITHUB_STEP_SUMMARY