Skip to main content

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-morph to 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):

  1. CLI flags
  2. Real environment (shell/CI)
  3. .env (auto-loaded)
  4. .prdoc.yaml
  5. 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/--path flow is perfect for quick experiments. In CI you’ll typically use --pr so 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 (node child process; installed in your repo).
    • Plugin interface (entry points) for community extractors and indexers.
  • 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 --yes in 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 node and ts-morph automatically (prdoc diagnose to 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 --verbose and confirm docs are matched by your docs.include globs.

  • Git apply failed
    Ensure the patch headers match repo paths. prdoc uses git apply -p0 (no a/ b/ prefixes). If your patch has prefixes, re-generate without them.

  • TypeScript extractor not working
    Run prdoc diagnose. You need node on PATH and ts-morph in 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 (narrow docs.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_extractor
    • prdoc.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)

Source distribution for prdocc 0.1.6
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)

Table of built distributions (wheels) for prdocc 0.1.6
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.6 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page