From pipecat-dev
Updates docs repo pages to match Python source changes on current branch: analyzes git diff in pipecat modules, maps files to docs, edits constructors, params, and event handlers.
npx claudepluginhub pipecat-ai/pipecat --plugin pipecat-devThis skill uses the workspace's default tool permissions.
Update documentation pages to reflect source code changes on the current branch. Analyzes the diff against main, maps changed source files to their corresponding doc pages, and makes targeted edits.
Manages MkDocs sites and standalone markdown files: initialize, generate, update docs, create change summaries. Triggers for 'create docs', 'write README', 'changelog' requests.
Verifies documentation references (file paths, CLI commands, config keys, env vars) against codebase and proposes updates for git diff-affected docs.
Share bugs, ideas, or general feedback.
Update documentation pages to reflect source code changes on the current branch. Analyzes the diff against main, maps changed source files to their corresponding doc pages, and makes targeted edits.
/update-docs [DOCS_PATH]
DOCS_PATH (optional): Path to the docs repository root. If not provided, ask the user.Examples:
/update-docs /Users/me/src/docs/update-docsIf DOCS_PATH was provided as an argument, use it. Otherwise, ask the user for the path to their docs repository.
Verify the path exists and contains server/services/ subdirectory.
Get the current pipecat branch name:
git rev-parse --abbrev-ref HEAD
In the docs repo, create a new branch off main with a matching name:
cd DOCS_PATH && git checkout main && git pull && git checkout -b {branch-name}-docs
For example, if the pipecat branch is feat/new-service, the docs branch becomes feat/new-service-docs.
All doc edits in subsequent steps are made on this branch.
Run:
git diff main..HEAD --name-only
Filter to files that could affect documentation:
src/pipecat/services/**/*.py (service implementations)src/pipecat/transports/**/*.py (transport implementations)src/pipecat/serializers/**/*.py (serializer implementations)src/pipecat/processors/**/*.py (processor implementations)src/pipecat/audio/**/*.py (audio utilities)src/pipecat/turns/**/*.py (turn management)src/pipecat/observers/**/*.py (observers)src/pipecat/pipeline/**/*.py (pipeline core)Ignore __init__.py, __pycache__, test files, and files that only contain type re-exports.
For each changed source file, find the corresponding doc page. Read the mapping file at .claude/skills/update-docs/SOURCE_DOC_MAPPING.md and apply its tiered lookup: tier 1 (known exceptions) → tier 2 (pattern matching) → tier 3 (search fallback). First match wins.
For each mapped pair:
git diff main..HEAD -- <source_file>Identify what changed by comparing source to docs:
__init__ signature to the Configuration section's <ParamField> entriesInputParams(BaseModel) class fields to the InputParams table_register_event_handler calls and event handler definitions to Event Handlers sectionFor each doc page that needs updates, edit only the sections that need changes. Preserve all other content exactly as-is.
<ParamField> tags, use them; if it uses tables, use tablesConfiguration (constructor params):
<ParamField path="name" type="type" default="value"> format if the page already uses itInputParams (runtime settings):
| Parameter | Type | Default | Description |InputParams(BaseModel) classUsage (code examples):
Notes:
Event Handlers:
Overview / Key Features / Prerequisites:
Guides at DOCS_PATH/guides/ reference specific class names, parameters, imports, and code patterns. After completing reference doc edits, check if any guides need updates too.
For each changed source file, collect the class names, renamed parameters, and changed imports from the diff. Search the guides directory:
grep -rl "ClassName\|old_param_name" DOCS_PATH/guides/
For each guide that references changed code:
Guide directories:
guides/learn/ — conceptual tutorials (pipeline, LLM, STT, TTS, etc.)guides/fundamentals/ — practical how-tos (metrics, recording, transcripts, etc.)guides/features/ — feature-specific guides (Gemini Live, OpenAI audio, WhatsApp, etc.)guides/telephony/ — telephony integration guides (Twilio, Plivo, Telnyx, etc.)After processing all mapped pairs, check for two kinds of gaps:
Missing pages: Source files that had no doc page mapping (neither tier 1, 2, nor 3) and are not marked as "(skip)". For each, tell the user:
Missing sections: Mapped doc pages that are missing standard sections compared to the source. For example, a transport page with no Configuration section, or a service page with no InputParams table when the source defines InputParams(BaseModel). Flag these and offer to add the missing sections.
If the user wants a new page, do all three of the following:
Create the new .mdx file using this template structure:
---
title: "Service Name"
description: "Brief description"
---
## Overview
[Description from class docstring or source analysis]
<CardGroup cols={2}>
[Cards for API reference and examples if available]
</CardGroup>
## Installation
```bash
pip install "pipecat-ai[package-name]"
[Environment variables and account setup]
[ParamField entries for constructor params]
[Table of InputParams fields, if the service has them]
[Minimal working example]
[Important caveats]
[Event table and example code]
#### 8b: Add to docs.json
Add the new page path to `DOCS_PATH/docs.json` in the correct navigation group. The path format is `server/services/{category}/{provider}` (without the `.mdx` extension).
Find the matching group in the navigation structure:
- **STT** → `"group": "Speech-to-Text"` under Services
- **TTS** → `"group": "Text-to-Speech"` under Services
- **LLM** → `"group": "LLM"` under Services
- **S2S** → `"group": "Speech-to-Speech"` under Services
- **Transport** → `"group": "Transport"` under Services
- **Serializer** → `"group": "Serializers"` under Services
- **Image generation** → `"group": "Image Generation"` under Services
- **Video** → `"group": "Video"` under Services
- **Memory** → `"group": "Memory"` under Services
- **Vision** → `"group": "Vision"` under Services
- **Analytics** → `"group": "Analytics & Monitoring"` under Services
Insert the new entry **alphabetically** within the group's `pages` array. For example, adding a new STT service "foo":
```json
{
"group": "Speech-to-Text",
"pages": [
"server/services/stt/assemblyai",
"server/services/stt/aws",
...
"server/services/stt/foo",
...
]
}
Add a new row to the correct category table in DOCS_PATH/server/services/supported-services.mdx.
Use this format:
| [DisplayName](/server/services/{category}/{provider}) | `pip install "pipecat-ai[package]"` |
To determine the correct values:
pyproject.toml extras or the import pattern in the source code. For example, if the service is in src/pipecat/services/foo/, the package is typically foo.No dependencies required instead.Insert the new row alphabetically within the table. Match the column alignment of the existing rows.
After all edits are complete, print a summary:
## Documentation Updates
### Updated reference pages
- `server/services/stt/deepgram.mdx` — Updated Configuration (added `new_param`), InputParams (updated `language` default)
- `server/services/tts/elevenlabs.mdx` — Updated Event Handlers (added `on_connected`)
### Updated guides
- `guides/learn/speech-to-text.mdx` — Updated code example (renamed `old_param` → `new_param`)
### New service pages
- `server/services/tts/newprovider.mdx` — Created page, added to docs.json (Text-to-Speech), added to supported-services.mdx
### Unmapped source files
- `src/pipecat/services/newprovider/tts.py` — NewProviderTTSService (no doc page exists)
### Skipped files
- `src/pipecat/services/ai_service.py` — internal base class
services/google/google.py are shared bases. Check which services import from them and update all affected doc pages.Before finishing, verify:
docs.json in the correct group, alphabeticallysupported-services.mdx in the correct table, alphabetically