docs: agentic docs-update workflow#35
Merged
AaronForinton merged 10 commits intomainfrom Mar 24, 2026
Merged
Conversation
# Conflicts: # src/poly/docs/docs/tutorials/build-an-agent.md
- Add mkdocs-gen-files script that auto-generates reference/cli-options.md
from poly --help output at build time
- Add mkdocs-macros hook exposing {{ adk_version }} in all doc pages
- Update mkdocs.yml to register gen-files and macros plugins, add
CLI options and Changelog nav entries
- Upgrade docs workflows to Python 3.14 and install poly before building
so the gen script can call poly --help
- Add changelog copy step so CHANGELOG.md is included in the site
- Broaden publish-docs trigger to rebuild when src/, CHANGELOG.md,
or pyproject.toml change
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds a GitHub Actions workflow that runs on every merge to main (when src/ or pyproject.toml changes). It diffs the merged code against the previous commit, sends the diff and all current docs to Claude, and applies any suggested updates. If Claude changes any files, the workflow opens a PR for human review before the changes are merged. New files: - .github/workflows/auto-update-docs.yaml — the workflow - docs/scripts/update_docs.py — the agent script Requires ANTHROPIC_API_KEY to be set as a repository secret. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AaronForinton
changed the title
AaronForinton
changed the title
- Resolve symlinks before path safety check to block traversal attacks - Add existing-file guard so Claude cannot create new files - Fix truncation message showing wrong character limit - Increase max_tokens 8096 -> 16384 for multi-file rewrites - Wrap API call in try/except to avoid failing CI on rate-limit errors - Fix no_updates_needed exit inside loop (set flag, break, check after) - Log stderr from failed subprocess calls instead of silently dropping - Move PR summary to /tmp so it is not staged by git add docs/ - Switch to --body-file in gh pr create to avoid shell injection risk - Drop pyproject.toml from trigger paths (version-only bumps are noise) - Downgrade workflow Python from 3.14 to 3.11 (anthropic needs only 3.8+) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AaronForinton
changed the title
bplevin36
approved these changes
Mar 23, 2026
Contributor
bplevin36
left a comment
bplevin36
left a comment
There was a problem hiding this comment.
will be interesting to see how well this works!
Contributor
Author
|
@bplevin36 I think we'll have to put a company Claude API key in the Repo secrets before it does anything, I'm not on the company Claude yet though! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a GitHub Actions workflow that automatically keeps the docs in sync with the codebase. Every time a PR is merged to main that touches `src/`, the workflow diffs what changed, sends the diff and all current docs to Claude, and opens a new PR with any suggested updates for human review before they are merged.
Motivation
The docs are fully hand-maintained today. Any new CLI flag, changed command behaviour, new resource type, or schema change requires a manual docs PR — and that update often doesn't happen. This automates the detection and drafting of those updates.
Changes
Test strategy
Checklist
Setup required
One secret must be added before the workflow will do anything:
Settings → Secrets and variables → Actions → New repository secret
`GITHUB_TOKEN` (used to open the docs PR) is provided automatically by GitHub — no setup needed.
How it works