diff --git a/.claude/skills/update-docs/SKILL.md b/.claude/skills/update-docs/SKILL.md new file mode 100644 index 000000000..f24d56f00 --- /dev/null +++ b/.claude/skills/update-docs/SKILL.md @@ -0,0 +1,250 @@ +--- +name: update-docs +description: Update documentation pages to match source code changes on the current branch +--- + +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. + +## Arguments + +``` +/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-docs` + +## Instructions + +### Step 1: Resolve docs path + +If `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. + +### Step 2: Create docs branch + +Get the current pipecat branch name: +```bash +git rev-parse --abbrev-ref HEAD +``` + +In the docs repo, create a new branch off main with a matching name: +```bash +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. + +### Step 3: Detect changed source files + +Run: +```bash +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. + +### Step 4: Map source files to doc pages + +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.** + +### Step 5: Analyze each source-doc pair + +For each mapped pair: + +1. **Read the full source file** to understand current state +2. **Read the diff** for that file: `git diff main..HEAD -- ` +3. **Read the current doc page** in full + +Identify what changed by comparing source to docs: + +- **Constructor parameters**: Compare `__init__` signature to the Configuration section's `` entries +- **InputParams fields**: Compare `InputParams(BaseModel)` class fields to the InputParams table +- **Event handlers**: Compare `_register_event_handler` calls and event handler definitions to Event Handlers section +- **Class names / imports**: Check if Usage examples reference correct names +- **Behavioral changes**: Check if Notes section needs updating + +### Step 6: Make targeted edits + +For each doc page that needs updates, edit **only the sections that need changes**. Preserve all other content exactly as-is. + +#### Rules + +- **Never remove content** unless the corresponding source code was removed +- **Never rewrite sections** that are already accurate +- **Match existing formatting** — if the page uses `` tags, use them; if it uses tables, use tables +- **Keep descriptions concise** — match the tone and length of surrounding content +- **Preserve CardGroup, links, and examples** unless they reference removed functionality +- **Don't touch frontmatter** unless the class was renamed + +#### Section-specific guidance + +**Configuration** (constructor params): +- Use `` format if the page already uses it +- Add new params in logical order (required first, then optional) +- Remove params that no longer exist in source +- Update types/defaults that changed + +**InputParams** (runtime settings): +- Use markdown table format: `| Parameter | Type | Default | Description |` +- Match the field names and types from the `InputParams(BaseModel)` class +- Include the default values from the source + +**Usage** (code examples): +- Update import paths, class names, and parameter names +- Only modify examples if they would break or be misleading with the new API +- Don't rewrite working examples just to add new optional params + +**Notes**: +- Add notes for new behavioral gotchas or breaking changes +- Remove notes about limitations that were fixed +- Keep existing notes that are still accurate + +**Event Handlers**: +- Update the event table and example code +- Add new events, remove deleted ones +- Update handler signatures if they changed + +**Overview / Key Features / Prerequisites**: +- Only update if the PR fundamentally changes what the service does (new capability, removed capability, renamed class) +- Most PRs will NOT need changes to these sections + +### Step 7: Update guides + +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: +```bash +grep -rl "ClassName\|old_param_name" DOCS_PATH/guides/ +``` + +For each guide that references changed code: +1. Read the full guide +2. Update class names, parameter names, import paths, and code examples that are now incorrect +3. **Don't rewrite prose** — only fix the specific references that changed +4. Leave guides alone if they reference the service generally but don't use any changed APIs + +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.) + +### Step 8: Identify doc gaps + +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: +- The source file path +- The main class(es) it defines +- Whether a new doc page should be created + +**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, create it using this template structure: +``` +--- +title: "Service Name" +description: "Brief description" +--- + +## Overview + +[Description from class docstring or source analysis] + + + [Cards for API reference and examples if available] + + +## Installation + +```bash +pip install "pipecat-ai[package-name]" +``` + +## Prerequisites + +[Environment variables and account setup] + +## Configuration + +[ParamField entries for constructor params] + +## InputParams + +[Table of InputParams fields, if the service has them] + +## Usage + +### Basic Setup + +```python +[Minimal working example] +``` + +## Notes + +[Important caveats] + +## Event Handlers + +[Event table and example code] +``` + +### Step 9: Output summary + +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`) + +### 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 +``` + +## Guidelines + +- **Be conservative** — only change what the diff warrants. Don't "improve" docs beyond what changed in source. +- **Read before editing** — always read the full doc page before making changes so you understand the existing structure. +- **Preserve voice** — match the writing style of the existing doc page, don't impose a different tone. +- **One PR at a time** — this skill operates on the current branch's diff against main. Don't look at other branches. +- **Parallel analysis** — when multiple source files map to different doc pages, analyze and edit them in parallel for efficiency. +- **Shared source files** — files like `services/google/google.py` are shared bases. Check which services import from them and update all affected doc pages. + +## Checklist + +Before finishing, verify: + +- [ ] All changed source files were checked against the mapping table +- [ ] Each doc page edit matches the actual source code change (not guessed) +- [ ] No content was removed unless the corresponding source was removed +- [ ] New parameters have accurate types and defaults from source +- [ ] Formatting matches the existing page style +- [ ] Guides referencing changed APIs were checked and updated +- [ ] Unmapped files were reported to the user diff --git a/.claude/skills/update-docs/SOURCE_DOC_MAPPING.md b/.claude/skills/update-docs/SOURCE_DOC_MAPPING.md new file mode 100644 index 000000000..03e6cbbf1 --- /dev/null +++ b/.claude/skills/update-docs/SOURCE_DOC_MAPPING.md @@ -0,0 +1,79 @@ +# Source-to-Doc Mapping + +Maps pipecat source files to their documentation pages. Source paths are relative to `src/pipecat/`. Doc paths are relative to `DOCS_PATH`. + +## Name mismatches + +These source paths don't follow the standard `services/{provider}/{type}.py` → `server/services/{type}/{provider}.mdx` pattern. + +| Source path | Doc page | +|---|---| +| `services/google/llm.py` | `server/services/llm/gemini.mdx` | +| `services/google/llm_vertex.py` | `server/services/llm/google-vertex.mdx` | +| `services/google/google.py` | (shared base — check which services use it) | +| `services/google/gemini_live/**` | `server/services/s2s/gemini-live.mdx` | +| `services/google/gemini_live/llm_vertex.py` | `server/services/s2s/gemini-live-vertex.mdx` | +| `services/aws_nova_sonic/**` | `server/services/s2s/aws.mdx` | +| `services/ultravox/**` | `server/services/s2s/ultravox.mdx` | +| `services/grok/realtime/**` | `server/services/s2s/grok.mdx` | +| `services/openai/realtime/**` | `server/services/s2s/openai.mdx` | +| `processors/frameworks/rtvi.py` | `server/frameworks/rtvi/rtvi-processor.mdx` and `server/frameworks/rtvi/rtvi-observer.mdx` | +| `processors/transcript_processor.py` | `server/utilities/transcript-processor.mdx` | +| `processors/user_idle_processor.py` | `server/utilities/user-idle-processor.mdx` | +| `processors/idle_frame_processor.py` | `server/pipeline/pipeline-idle-detection.mdx` | +| `pipeline/task.py` | `server/pipeline/pipeline-task.mdx` | +| `pipeline/runner.py` | `server/utilities/runner/guide.mdx` | +| `transports/base_transport.py` | `server/services/transport/transport-params.mdx` | + +## Skip list + +These files should never trigger doc updates. + +| Pattern | Reason | +|---|---| +| `services/ai_service.py` | Internal base class | +| `services/stt_service.py` | Internal base class | +| `services/tts_service.py` | Internal base class | +| `services/llm_service.py` | Internal base class | +| `services/websocket_service.py` | Internal base class | +| `services/openai_realtime_beta/**` | Deprecated | +| `services/openai_realtime/**` | Deprecated | +| `services/gemini_multimodal_live/**` | Deprecated | +| `services/aws/agent_core.py` | Internal | +| `services/aws/sagemaker/**` | No doc page | +| `transports/base_input.py` | Internal base class | +| `transports/base_output.py` | Internal base class | +| `transports/websocket/client.py` | No doc page | +| `serializers/base_serializer.py` | Internal base class | +| `serializers/protobuf.py` | Internal | +| `processors/audio/**` | Internal | +| `pipeline/pipeline.py` | Core architecture, not a service doc | + +## Pattern matching + +For files not in the tables above, apply these patterns. Convert underscores to hyphens in provider names for doc filenames. + +| Source pattern | Doc pattern | +|---|---| +| `services/{provider}/stt*.py` | `server/services/stt/{provider}.mdx` | +| `services/{provider}/tts*.py` | `server/services/tts/{provider}.mdx` | +| `services/{provider}/llm*.py` | `server/services/llm/{provider}.mdx` | +| `services/{provider}/image*.py` | `server/services/image-generation/{provider}.mdx` | +| `services/{provider}/video*.py` | `server/services/video/{provider}.mdx` | +| `services/{provider}/realtime/**` | `server/services/s2s/{provider}.mdx` | +| `transports/{name}/**` | `server/services/transport/{name}.mdx` | +| `serializers/{name}.py` | `server/services/serializers/{name}.mdx` | +| `observers/**` | `server/utilities/observers/` (match by class name) | +| `audio/vad/**` | `server/utilities/audio/` (match by class name) | +| `audio/filters/**` | `server/utilities/audio/` (match by class name) | +| `audio/mixers/**` | `server/utilities/audio/` (match by class name) | +| `processors/filters/**` | `server/utilities/filters/` (match by class name) | + +If the doc file doesn't exist at the resolved path, the file is **unmapped**. + +## Search fallback + +For files that don't match any table or pattern above: +1. Extract the main class name(s) from the source file +2. Search the docs directory for that class name: `grep -r "ClassName" DOCS_PATH/server/` +3. If found in a doc page, use that as the mapping