Update docs build to deploy from gh-pages branch to docs/ directory with preserved branch history - #5605

This PR updates the documentation build and deployment process to use branch-based deployment instead of the GitHub Pages action, with documentation organized in a docs/ directory while preserving existing branch content for future multi-directory usage.

Changes Made

Workflow Updates (.github/workflows/build-docs.yml)

• Replaced GitHub Pages action deployment with branch-based deployment using peaceiris/actions-gh-pages@v3
• Combined build and deploy jobs into a single build-and-deploy job for efficiency
• Updated permissions from pages: write, id-token: write to contents: write to allow pushing to branches
• Removed GitHub Pages environment configuration as it's no longer needed
• Added destination_dir: docs to deploy documentation to the docs/ directory in the gh-pages branch
• Removed force_orphan: true to preserve existing content on the gh-pages branch for future multi-directory usage

Action Updates (.github/actions/docs-build/action.yml)

• Removed actions/configure-pages@v3 setup step since we're not using GitHub Pages action
• Updated descriptions to reflect the new branch-based deployment approach
• Maintained backward compatibility for artifact uploads

Key Benefits

1. Simplified deployment: Deploys directly to gh-pages branch instead of through GitHub Pages action
2. Preserved branch history: Maintains existing branch content and history for future multi-directory usage
3. Reduced complexity: Eliminates the need for Pages-specific configuration and permissions
4. Maintained functionality: All existing build processes and artifact generation remain unchanged
5. Organized structure: Documentation is now deployed to the docs/ directory for better organization
6. Future-ready: Allows for additional subdirectories for pr-reviews, multi-versioned docs, etc.

Configuration Required

Repository maintainers will need to update the GitHub Pages settings to deploy from the gh-pages branch instead of GitHub Actions. The workflow will automatically create the gh-pages branch on the first deployment, with documentation located in the docs/ directory.

Technical Details

The deployment now uses the well-established peaceiris/actions-gh-pages@v3 action with the following configuration:

• Publishes from the _site directory (same as before)
• Uses the default GITHUB_TOKEN for authentication
• Deploys to the gh-pages branch with preserved history (no force_orphan)
• Places documentation in the docs/ directory within the gh-pages branch
• Preserves existing content on the branch for future multi-directory usage

This change maintains all existing documentation generation logic while switching to a more standard branch-based deployment approach with organized directory structure and preserved branch history.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.