pipecat/docs/api

Pipecat API Documentation

This directory contains the source files for auto-generating Pipecat's API reference documentation.

Building Documentation

From this directory:

# Build docs (warnings shown but don't fail the build)
cd docs/api && uv run ./build-docs.sh

# Build with strict mode (warnings treated as errors)
cd docs/api && uv run ./build-docs.sh --strict

The build script will:

1. Install documentation dependencies via uv sync --group docs
2. Clean previous build output
3. Run sphinx-build to generate HTML documentation
4. Open the result in your browser (macOS)

Directory Structure

.
├── api/            # Auto-generated API documentation (created during build)
├── _build/         # Built documentation output
├── conf.py         # Sphinx configuration (mock imports, extensions, etc.)
├── index.rst       # Main documentation entry point
├── build-docs.sh   # Local build script
└── rtd-test.sh     # ReadTheDocs test build script (uses pip, not uv)

How It Works

• conf.py runs sphinx-apidoc during Sphinx's setup() phase to generate .rst files from Python source
• Sphinx autodoc imports each module to extract docstrings
• Modules with unavailable dependencies are listed in autodoc_mock_imports in conf.py
• Napoleon extension converts Google-style docstrings to reStructuredText

Troubleshooting

Module not appearing in docs:

1. Check the build output for autodoc: failed to import warnings
2. If the module has an unresolvable import dependency, add it to autodoc_mock_imports in conf.py
3. Verify the module is importable: uv run python -c "import pipecat.module.name"

Duplicate object warnings:

These come from re-export modules or Sphinx discovering the same class through multiple import paths. Usually cosmetic.

Docstring formatting warnings:

Docstrings use reStructuredText, not Markdown. Common issues:

• Use Example:: with indented code blocks, not ```python
• Ensure blank lines between directive content and subsequent sections
• Use Parameters: (not Attributes:) for dataclass field documentation to avoid duplicate entries