pr-doc-sync (prdoc)
Keep your docs in lockstep with your code.
prdoc is a CLI + GitHub Action that detects code→doc drift in pull requests, proposes Markdown patches (via an LLM), and can apply/commit them automatically — so reviewers see doc updates alongside code changes.
- Language-aware: Python (
libcst) + TypeScript/JavaScript (ts-morph) + plugin interface for more. - Docs-aware: Locates & searches repo docs (
.md,.rst,.mdx) to find the best spots to edit. - LLM-guarded: Rate-limit + token-budget guard with clear, human-readable cost estimates.
- Resilient: Fallback heuristic patch when LLM is unavailable.
- Pretty CLI: Rich-styled output, progress bars, and a detailed
prdoc help.
Install
# Recommended
pipx install prdoc
# or
pip install prdoc
Python 3.9+ required. For TypeScript symbol extraction, install Node.js and add
ts-morphto your project:npm i -D ts-morph
Quickstart
Show help:
prdoc help
Preview (read-only) suggested patches for a PR in CI:
# In GitHub Actions, with GITHUB_TOKEN available:
prdoc sync --pr 123 --dry-run --comment
Apply patches locally (non-interactive):
# Pipe the unified diff (from 'sync') into apply, or feed your own patch
prdoc apply --yes --commit-msg "docs: align with PR #123"
If you’re testing locally without PR context, see Local Dry Run below.
Configuration
You can configure via CLI flags, env vars, or .prdoc.yaml. Precedence (highest → lowest):
- CLI flags
- Real environment (shell/CI)
.env(auto-loaded).prdoc.yaml- Defaults
Environment
# Required for GitHub API
export GITHUB_TOKEN=ghp_********************************
# Pick one LLM provider and key:
export OPENAI_API_KEY=sk-********************************
# or
export GROQ_API_KEY=gsk_********************************
# Optional: enable anonymous telemetry for this run
export PRDOC_TELEMETRY=1
.prdoc.yaml (example)
# Which LLM backend to use by default
provider: openai
model: gpt-5-thinking # or your preferred model id
# Glob patterns to find docs
docs:
include:
- "docs/**/*.md"
- "README.md"
exclude:
- "docs/archive/**"
# Optional: vector index plugin (Chroma)
chroma:
enabled: false
persist_dir: .prdoc/chroma
# Logging
verbose: false
Commands
Global flags
--verbose / -v Enable debug logging
--no-color Disable ANSI colors
--telemetry/--no-telemetry Opt in/out (for this run)
--version Print version and exit
prdoc help [COMMAND]
Pretty, sectioned help with examples.
prdoc help
prdoc help sync
prdoc help apply
prdoc help diagnose
prdoc help telemetry
prdoc sync
Analyze a PR’s code changes, search docs, generate unified diff patches, and optionally post a summary comment (CI).
Common flags (some may be CI-only):
--pr <num> Pull request number to analyze
--comment Post a Markdown summary comment to the PR
--dry-run Print patches to stdout (do not write)
--max-cost <USD> Abort if estimated LLM spend exceeds this amount
Local Dry Run (no PR context)
If you just want to try the engine on a couple of doc files:
# Example: tell prdoc how to update specific docs (dry-run only)
prdoc sync -i "tighten intro and add usage example" -p README.md -p docs/guide.md -r openai -m gpt-5-thinking
The local
-i/--instruction+-p/--pathflow is perfect for quick experiments. In CI you’ll typically use--prso prdoc reads diff + doc candidates automatically.
prdoc apply
Read a unified diff from STDIN, apply via git apply -p0, commit, and push.
--yes Non-interactive (no confirmation)
--commit-msg/-m Commit message to use
--branch <name> Target branch (optional, will push current HEAD if omitted)
Example:
# From a file:
cat patch.diff | prdoc apply --yes -m "docs: synchronize with PR #123"
# From sync output:
prdoc sync --pr 123 --dry-run | prdoc apply --yes
prdoc diagnose
Pretty environment check: tokens, Node.js/ts-morph presence, versions, and quick tips.
prdoc diagnose
Features (what happens under the hood)
- Diff parsing: Reads the PR’s diff to identify changed symbols and files.
- Symbol extractors:
- Python via
libcst(functions, classes, methods, signatures). - TS/JS via
ts-morph(nodechild process; installed in your repo). - Plugin interface (entry points) for community extractors and indexers.
- Python via
- Doc discovery & search:
- Glob scans for docs; simple trigram index for fuzzy search.
- Optional Chroma vector index plugin (for larger repos).
- Patch generation:
- Prompt templates (Jinja) craft “diff → doc patch” instructions.
- LLM client abstraction with retries and provider swapping (OpenAI/Groq).
- Resilience:
- LLM guard: rate-limit + token-budget checks with cost estimation.
- Fallback heuristic: returns a simple search-replace style diff when offline.
- CI-friendly:
- Composite Action wrapper (comment-only mode).
- Bot comment renderer (clean, non-intrusive PR summary).
GitHub Actions (minimal)
name: prdoc
on:
pull_request:
branches: [main]
jobs:
sync:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pipx install prdoc
- env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} # or GROQ_API_KEY
run: |
prdoc sync --pr ${{ github.event.pull_request.number }} --comment --dry-run
For full automation, run
prdoc apply --yesin a separate job/PR after reviewers accept the patch.
TypeScript/JavaScript support
- Requires Node.js and a local dev dependency on
ts-morph(so your repo controls the exact version). - prdoc will detect
nodeandts-morphautomatically (prdoc diagnoseto verify). - Symbol extraction provides function/class/variable identifiers used to target doc snippets.
Telemetry (opt-in)
Anonymous, minimal counts + timings only (no code, no docs, no repo names). Helps us prioritize performance and UX.
Enable for a run:
prdoc sync --telemetry --pr 123
Disable explicitly:
prdoc sync --no-telemetry --pr 123
Or set via env:
export PRDOC_TELEMETRY=1
Troubleshooting
-
No patches suggested
The change may not touch public symbols or documented sections. Try--verboseand confirm docs are matched by yourdocs.includeglobs. -
Git apply failed
Ensure the patch headers match repo paths. prdoc usesgit apply -p0(noa/b/prefixes). If your patch has prefixes, re-generate without them. -
TypeScript extractor not working
Runprdoc diagnose. You neednodeon PATH andts-morphin your project (npm i -D ts-morph). -
Budget exceeded / rate limited
Lower--max-cost, pick a cheaper model, or reduce the number of candidate docs (narrowdocs.include).
Versioning & Release
- Semantic Versioning.
- PyPI releases are built with Poetry and published via GitHub Actions (PyPI Trusted Publisher / OIDC).
Contributing
- Issues & PRs welcome!
- Plugin authors: expose entry points under:
prdoc.symbol_extractorprdoc.doc_indexer
License
MIT © Bethvour
Metadata
Release files for prdocc 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| prdocc-0.1.6.tar.gz | 35.2 kB | With provenance | Details for prdocc-0.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| prdocc-0.1.6-py3-none-any.whl | Python 3 | none | any | Details for prdocc-0.1.6-py3-none-any.whl |
Total release size: 75.1 kB
Release files / prdocc-0.1.6.tar.gz
| Download URL | prdocc-0.1.6.tar.gz |
|---|---|
| Size | 35.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2073a85e784e9883e87515a5277a416fb45aff3887f7a455ccb34b9aaf0f24da
|
|
BLAKE2b-256 checksum How to use checksums |
86882857e36d08f74f28f625ffd7356d2039058b18628aca092872bb42f0ccf9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2025.
Transparency logRelease files / prdocc-0.1.6-py3-none-any.whl
| Download URL | prdocc-0.1.6-py3-none-any.whl |
|---|---|
| Size | 39.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a9b8934e535508b45b42c6dbb2bb85074c44ad15ad9fddec89862b7ad960907a
|
|
BLAKE2b-256 checksum How to use checksums |
53a87218df382fc9150bda2e44074b7d90a77496bc6efa186cc1ef9f61dbec08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2025.
Transparency logSecurity for prdocc 0.1.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for prdocc-0.1.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.