fix(ci): install mkdocs deps so docs deploy works#5
Conversation
deploy-docs ran 'uv run mkdocs gh-deploy' but mkdocs was never a declared dependency, so it failed with 'Failed to spawn: mkdocs'. Add a 'docs' dependency group (mkdocs, mkdocs-material, pymdown-extensions) and run the deploy via 'uv run --group docs'.
|
Warning Review limit reached
More reviews will be available in 42 minutes and 10 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Reviewer's guide (collapsed on small PRs)Reviewer's GuideAdds a dedicated docs dependency group for MkDocs and updates the release workflow to install and use those docs dependencies when deploying documentation, updating the uv lockfile accordingly. Sequence diagram for docs deployment using uv docs dependency groupsequenceDiagram
actor Developer
participant GitHubActions as GitHub_Actions
participant SetupEnv as setup-python-env
participant Uv as uv
participant Mkdocs as mkdocs
Developer->>GitHubActions: push tag / trigger release
GitHubActions->>SetupEnv: uses .github/actions/setup-python-env
GitHubActions->>Uv: run uv run --group docs mkdocs gh-deploy --force
Uv->>Uv: resolve docs dependency group
Uv->>Mkdocs: mkdocs gh-deploy --force
Mkdocs-->>GitHubActions: publish docs to hosting
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new docs dependency group in pyproject.toml containing mkdocs, mkdocs-material, and pymdown-extensions, and updates the uv.lock file accordingly. Feedback highlights that the GitHub Actions workflow file needs to be updated to support the new documentation deployment command. Additionally, it is recommended to include the docs group in the default installation configuration to ensure local development commands do not fail.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| docs = [ | ||
| "mkdocs>=1.5", | ||
| "mkdocs-material>=9.5", | ||
| "pymdown-extensions>=10", | ||
| ] |
There was a problem hiding this comment.
Missing Workflow Updates
The PR description mentions:
Deploy via
uv run --group docs mkdocs gh-deploy --force.
However, the GitHub Actions workflow file (e.g., .github/workflows/release-please.yml) is not modified in this pull request. Without updating the workflow file to use this new command, the documentation deployment in CI will continue to fail. Please include the changes to your workflow file in this pull request.
There was a problem hiding this comment.
Addressed in 32d3ed6 — the manual docs-deploy was updated to as well.
| docs = [ | ||
| "mkdocs>=1.5", | ||
| "mkdocs-material>=9.5", | ||
| "pymdown-extensions>=10", | ||
| ] |
There was a problem hiding this comment.
Local Development & Makefile Compatibility
Since docs is introduced as a separate dependency group, running make docs or make docs-test will now fail for local developers who set up their environment using make install (which runs uv sync and only installs the dev group by default).
To resolve this and maintain a seamless local development experience, you can either:
- Include the
docsgroup in thedevgroup using uv's group inheritance:dev = [ ... { group = "docs" } ]
- Configure
default-groupsunder[tool.uv]to include bothdevanddocsby default:[tool.uv] package = true default-groups = ["dev", "docs"]
There was a problem hiding this comment.
Building docs locally now works with . No Makefile target referenced mkdocs, so nothing else to update.
Same mkdocs-missing fix for the workflow_dispatch fallback, so it can be used to deploy docs for an already-tagged release.
![llamapreview[bot]](https://avatars.githubusercontent.com/in/1023541?s=60&v=4){kind=small}
There was a problem hiding this comment.
AI Code Review by LlamaPReview
🎯 TL;DR & Recommendation
Recommendation: Approve with suggestions
This PR fixes a critical CI failure by adding a dedicated docs dependency group and updating workflow commands. However, two maintainability improvements and a missing CI build check are suggested.
📄 Documentation Diagram
This diagram documents the updated documentation deployment workflow with the new docs dependency group.
sequenceDiagram
participant Workflow as Deploy Docs Job
participant CI as Setup Python Env
participant VEnv as Virtual Environment
participant MkDocs as MkDocs CLI
participant GitHub as GitHub Pages
Workflow->>CI: Checkout repository
CI->>VEnv: Install environment (uv sync --frozen)
note over VEnv: Now includes docs group
Workflow->>MkDocs: uv run --group docs mkdocs gh-deploy --force
note over Workflow,MkDocs: PR #35;5: Added --group docs flag<br/>to install mkdocs deps
MkDocs->>GitHub: Deploy site
🌟 Strengths
- Directly addresses the root cause of the deployment failure by declaring missing dependencies.
- Minimal changes with clear impact; verified locally.
| Priority | File | Category | Impact Summary (≤12 words) | Anchors |
|---|---|---|---|---|
| P2 | .github/workflows/release-please.yml |
Maintainability | quality CI job failed; may leave main red. | search:quality |
| P2 | pyproject.toml |
Maintainability | Unbounded version ranges risk silent breaking changes. | |
| P2 | .github/workflows/release-please.yml |
Testing | No CI step to verify docs build on every PR. | search:mkdocs build |
💡 Have feedback? We'd love to hear it in our GitHub Discussions.
✨ This review was generated by LlamaPReview Advanced, which is free for all open-source projects. Learn more.
| docs = [ | ||
| "mkdocs>=1.5", | ||
| "mkdocs-material>=9.5", | ||
| "pymdown-extensions>=10", | ||
| ] |
There was a problem hiding this comment.
P2 | Confidence: High
All three dependencies use “>=” without an upper bound. While this allows maximum flexibility, it risks breaking the documentation build silently when a future major version of mkdocs-material or pymdown-extensions introduces incompatible changes to plugins, templates, or markdown syntax. The project’s mkdocs.yml and custom plugins may not be forward‑compatible, leading to deployment failures that are hard to debug. Consider pinning to a known‑good range (e.g., ~=9.5 for mkdocs-material) to gain stability without becoming stale.
Code Suggestion:
docs = [
"mkdocs>=1.5,<2",
"mkdocs-material>=9.5,<10",
"pymdown-extensions>=10,<11",
]There was a problem hiding this comment.
Left unbounded to match the repo convention — the existing dependency group also pins with and no upper bound. Fine to revisit repo-wide if desired.
| - name: Deploy documentation | ||
| run: uv run mkdocs gh-deploy --force | ||
| run: uv run --group docs mkdocs gh-deploy --force |
There was a problem hiding this comment.
P2 | Confidence: Medium
The CI output shows the quality job failed (conclusion: failure), yet the PR description states deptry passed locally. This discrepancy suggests either a pre‑existing issue or a new problem introduced by the docs dependency group (e.g., deptry scanning the docs group and flagging unused packages). Without fixing this failure, the main branch may remain red after merge, masking future regressions. Since the failure details are not visible in the diff, this is a speculative observation based on CI status.
P2 | Confidence: Medium
Speculative: The workflows deploy documentation only during a release, but there is no step to verify that mkdocs build succeeds on every push or PR. This means a regression in the docs dependency group or in the documentation content could go undetected until a release fails. Adding a separate CI job (e.g., a docs-check step that runs uv run --group docs mkdocs build --strict) would catch broken docs early and increase confidence.
Code Suggestion:
# Example step to add to the existing workflow or a new job:
- name: Build documentation
run: uv run --group docs mkdocs build --strictEvidence: search:mkdocs build, path:.github/workflows/on-release-main.yml
There was a problem hiding this comment.
The quality failure was unrelated to this change (release-please-generated CHANGELOG.md/manifest vs prettier); fixed in 72134db by excluding those release-please-owned files from prettier. quality is green now.
The pre-commit 'quality' gate ran prettier over CHANGELOG.md and .release-please-manifest.json, which release-please regenerates each release in a format prettier rewrites — failing CI on every post-release PR. Exclude both from prettier so release-please owns them.
|
|
The review could not be posted after 3 attempts. Last error: claude-reviewThis is a targeted, well-scoped fix that correctly addresses the root cause of the docs deployment failure by adding a proper
Reviewed commit:
|
|
The review could not be posted after 3 attempts. Last error: claude-reviewThe fix is straightforward and correctly addresses the root cause — adding a dedicated
Model: claude-sonnet-4-6 · 6 agents · $0.162579 · ai-review-bot Inline comments (could not be anchored — listed by location):
|
![codexreviewbot[bot]](https://avatars.githubusercontent.com/in/3435464?s=60&v=4){kind=small}
There was a problem hiding this comment.
claude-review
✅ No issues found. PR approved for merge. Note: 1 CI check(s) still outstanding: quality (failed).
Additional skills activated:
comment-analyzer— 71 comment lines added or modified
Reviewed commit:e8b66babd077
Model: gpt-5 · 6 agents · $0.206717 · ai-review-bot
![anthropicreviewbot[bot]](https://avatars.githubusercontent.com/in/3485352?s=60&v=4){kind=small}
There was a problem hiding this comment.
claude-review
Since the last review, new commits introduced minor additional changes: a .pre-commit-config.yaml exclusion with a clear explanatory comment (low concern, well-documented). Two low-severity follow-up observations were flagged — no upper bounds on docs dependencies and no docs build step in the PR/push CI workflow — but neither is a blocker. The core fix remains sound and no new significant issues were introduced.
Additional skills activated:
comment-analyzer— 71 comment lines added or modified
Inline comments: 1
| Sev | Finding |
|---|---|
| 🟢 | FYI: No upper bounds on docs dependencies may cause silent breakage |
| 🟢 | FYI: No CI step to verify docs build on PRs |
Reviewed commit: 72134db26ed7
Model: claude-sonnet-4-6 · 6 agents · $0.165570 · ai-review-bot
| - id: prettier | ||
| exclude: ^{{cookiecutter.project_name}} | ||
| # CHANGELOG.md and .release-please-manifest.json are owned/regenerated by |
There was a problem hiding this comment.
FYI: Comment explains the exclusion rationale well
The added comment accurately describes why CHANGELOG.md and .release-please-manifest.json are excluded from prettier: they are owned and regenerated by release-please, and fighting prettier on each release would cause unnecessary churn. This is a good 'why' comment that will remain accurate as long as release-please is used. No issues found.
There was a problem hiding this comment.
claude-review
✅ All issues from the previous review have been resolved. PR approved for merge.
Additional skills activated:
comment-analyzer— 71 comment lines added or modified
Reviewed commit:72134db26ed7
Model: gpt-5 · 6 agents · $0.253315 · ai-review-bot
1 participant
The
deploy-docsjob in release-please.yml failed on the v0.2.0 release witherror: Failed to spawn: mkdocs— mkdocs was never a declared dependency, souv sync --frozennever installed it (the old release workflow had the same latent bug).Fix:
docsdependency group:mkdocs,mkdocs-material(the thememkdocs.ymluses),pymdown-extensions(forpymdownx.*markdown extensions).uv run --group docs mkdocs gh-deploy --force.Verified locally:
uv run --group docs mkdocs buildsucceeds;deptryclean; lockfile updated.Summary by Sourcery
Ensure documentation deployment installs and uses explicit MkDocs-related dependencies via a dedicated docs dependency group.
Bug Fixes:
Build:
CI:
claude-review
gpt-5comment-analyzer