Fix documentation workflow for proper GitHub Pages deployment #21
Conversation
- Enhanced workflow triggers to include pyproject.toml, README.md, and workflow file changes - Fixed deployment to copy files to docs/ directory for GitHub Pages compatibility - Removed duplicate build command that was running twice - Added comprehensive build verification before deployment - Implemented complete documentation branch cleanup to prevent old artifacts - Added proper .gitignore and README.md to documentation branch - Improved error handling and logging throughout the workflow 🪬 This fixes the documentation automation to trigger correctly and maintain a clean file structure
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughThe changes in this pull request focus on enhancing the documentation build and deployment workflow for the project. The key modifications include expanding the workflow triggers to monitor more files, simplifying and hardening the build step, and improving the deployment process by introducing build verification checks and refactoring the worktree handling. Changes
Sequence Diagram(s)sequenceDiagram
participant Workflow
participant BuildStep
participant DeploymentStep
Workflow->>BuildStep: Trigger on push/pull_request
BuildStep->>BuildStep: Clean documentation build
BuildStep->>BuildStep: Build documentation
BuildStep->>DeploymentStep: Notify successful build
DeploymentStep->>DeploymentStep: Verify documentation build
DeploymentStep->>DeploymentStep: Prepare deployment worktree
DeploymentStep->>DeploymentStep: Commit and push updated documentation
The sequence diagram above illustrates the key steps in the updated documentation workflow:
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes The changes in this pull request are of moderate complexity, involving updates to the workflow configuration file and enhancements to the documentation build and deployment process. While the overall changes are not overly complicated, the number of affected files and the variety of modifications (such as expanding triggers, simplifying build steps, and refactoring deployment handling) warrant a moderate review effort. Possibly related PRs
📜 Recent review detailsConfiguration used: CodeRabbit UI 💡 Knowledge Base configuration:
You can enable these sources in your CodeRabbit configuration. 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
This PR enhances the documentation workflow for proper GitHub Pages deployment by fixing trigger conditions, improving build verification, and establishing a clean file structure for the documentation branch.
- Enhanced workflow triggers to include important configuration files (pyproject.toml, README.md) and the workflow file itself
- Fixed deployment structure to copy files to docs/ directory for GitHub Pages compatibility
- Improved build process by removing duplicate commands and adding comprehensive verification
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (3)
.github/workflows/docs.yml (3)
88-92: Add error handling to pushd/popd (repeat of prior feedback)If docs-deploy doesn’t exist, subsequent git commands may run in the wrong dir. Add a guard.
Apply this diff:
- pushd docs-deploy + pushd docs-deploy || { echo "Failed to enter docs-deploy directory"; exit 1; } @@ - popd + popd || true
129-129: Add error handling to pushd here as well (repeat of prior feedback)Same rationale as above.
Apply this diff:
- pushd docs-deploy + pushd docs-deploy || { echo "Failed to enter docs-deploy directory"; exit 1; }
135-137: Fix multi-line commit message formatting (shell splits lines into separate commands)As-is, the second line is executed as its own command. Use multiple -m flags.
Apply this diff:
- git commit -m "Update documentation - -🪬 Generated with Sphinx from main branch" + git commit -m "Update documentation" -m "🪬 Generated with Sphinx from main branch"
🧹 Nitpick comments (1)
.github/workflows/docs.yml (1)
93-98: Consider deleting stale files during deploy for a clean siteIf files were removed from docs, they’ll persist without an explicit delete. Using rsync with --delete (or cleaning target before copy) avoids drift.
If you choose rsync in the earlier suggestion, that covers this. Otherwise:
- cp -a docs/sphinx/_build/html/. docs-deploy/docs/ + # Remove old content then copy fresh build + rm -rf docs-deploy/docs/* + cp -a docs/sphinx/_build/html/. docs-deploy/docs/
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.github/workflows/docs.yml(4 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-19T12:24:44.359Z
Learnt from: zacczakk
PR: 2phi/weac#16
File: .github/workflows/docs.yml:0-0
Timestamp: 2025-08-19T12:24:44.359Z
Learning: For the weac project's Sphinx documentation builds, do not use the -W flag to treat warnings as errors. The user prefers builds that don't fail on documentation warnings.
Applied to files:
.github/workflows/docs.yml
🪛 YAMLlint (1.37.1)
.github/workflows/docs.yml
[error] 51-51: trailing spaces
(trailing-spaces)
[error] 70-70: trailing spaces
(trailing-spaces)
[error] 76-76: trailing spaces
(trailing-spaces)
[error] 92-92: trailing spaces
(trailing-spaces)
[error] 95-95: trailing spaces
(trailing-spaces)
[error] 98-98: trailing spaces
(trailing-spaces)
[error] 103-103: syntax error: could not find expected ':'
(syntax)
🪛 actionlint (1.7.7)
.github/workflows/docs.yml
102-102: could not parse as YAML: yaml: line 102: could not find expected ':'
(syntax-check)
🔇 Additional comments (11)
.github/workflows/docs.yml (11)
10-12: Expanded path filters on push: LGTMIncluding pyproject.toml, README.md, and the workflow file will help catch meaningful docs rebuild triggers.
15-20: Expanded path filters on PRs: LGTMMirrors the push filters appropriately; good coverage.
49-56: Build flow aligns with project preference (no -W) and is soundThe clean → apidoc → html sequence is solid. Using SPHINXOPTS="--keep-going -n" honors the “don’t fail on warnings” preference from earlier feedback. Nice.
65-72: Good build verification gate before deployEarly exit when index.html is missing prevents publishing broken docs and saves time.
21-25: Permissions scope is appropriate for pushing to documentation branchcontents: write is sufficient and not overly broad. Good.
73-86: Worktree handling is robustPruning, fetching remote branch, and attaching/creating the local branch looks correct. Good use of
--force -B/-b.
58-60: Deployment gating looks correctDeploy is limited to push events on main. Sensible default to avoid PRs pushing.
1-1: Minor: Title emoji is consistent with commit messagingNice touch; no functional impact.
32-46: Dependency setup is reasonable for Sphinx buildsEditable install ensures autodoc can import the package during doc generation.
56-56: Explicit acknowledgment of “no warnings as errors” preferenceUsing
--keep-going -nand not-Waligns with your prior preference for Sphinx builds.
58-140: Operational check: ensure Pages is configured to documentation branch /docsSince you’re publishing into docs/ on the documentation branch, make sure repo Pages settings are “Branch: documentation / Folder: /docs”.
Would you like me to provide a one-time checklist or a script using the GitHub API to validate the Pages source configuration?
- Modified cleanup process to preserve existing .gitignore during branch cleanup - Changed .gitignore creation to be conditional - only creates if file doesn't exist - This allows manual customization of .gitignore on documentation branch to persist - Fixes destructive behavior that was overwriting custom ignore rules The workflow now: 1. Backs up .gitignore before cleanup (if exists) 2. Performs normal cleanup of documentation branch 3. Restores .gitignore after cleanup 4. Only creates default .gitignore on first deployment or if missing
- Ensured the presence of a .nojekyll file in the HTML output directory for GitHub Pages compatibility. - Removed redundant .gitignore and README.md creation steps to streamline the deployment process. - Updated deployment logic to improve efficiency and maintain a clean documentation branch. This change enhances the documentation workflow by ensuring proper deployment to GitHub Pages without unnecessary file generation.
🪬 This fixes the documentation automation to trigger correctly and maintain a clean file structure
Summary by CodeRabbit
Here are the updated release notes based on the provided summary:
Documentation
Chores