21aa50283e
Make -W (warnings as errors) opt-in via --strict flag instead of default, and update README to reflect uv-based workflow and current directory structure.
61 lines
2.1 KiB
Markdown
61 lines
2.1 KiB
Markdown
# Pipecat API Documentation
|
|
|
|
This directory contains the source files for auto-generating Pipecat's API reference documentation.
|
|
|
|
## Building Documentation
|
|
|
|
From this directory:
|
|
|
|
```bash
|
|
# 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
|