-
Notifications
You must be signed in to change notification settings - Fork 399
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #800 from pipecat-ai/mb/autogen-docs
Auto-generate API reference docs
- Loading branch information
Showing
19 changed files
with
378 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
name: Generate API Documentation | ||
|
||
on: | ||
release: | ||
types: [published] # Run on new release | ||
workflow_dispatch: # Manual trigger | ||
|
||
jobs: | ||
update-docs: | ||
runs-on: ubuntu-latest | ||
permissions: | ||
contents: write | ||
pull-requests: write | ||
|
||
steps: | ||
- uses: actions/checkout@v4 | ||
|
||
- name: Set up Python | ||
uses: actions/setup-python@v5 | ||
with: | ||
python-version: '3.12' | ||
|
||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install -r docs/api/requirements.txt | ||
pip install . | ||
- name: Generate API documentation | ||
run: | | ||
cd docs/api | ||
python generate_docs.py | ||
- name: Create Pull Request | ||
uses: peter-evans/create-pull-request@v5 | ||
with: | ||
commit-message: 'docs: Update API documentation' | ||
title: 'docs: Update API documentation' | ||
body: | | ||
Automated PR to update API documentation. | ||
- Generated using `docs/api/generate_docs.py` | ||
- Triggered by: ${{ github.event_name }} | ||
branch: update-api-docs | ||
delete-branch: true | ||
labels: | | ||
documentation |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
version: 2 | ||
|
||
build: | ||
os: ubuntu-22.04 | ||
tools: | ||
python: '3.12' | ||
|
||
sphinx: | ||
configuration: docs/api/conf.py | ||
|
||
python: | ||
install: | ||
- requirements: docs/api/requirements.txt | ||
- method: pip | ||
path: . |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= | ||
SPHINXBUILD ?= sphinx-build | ||
SOURCEDIR = . | ||
BUILDDIR = _build | ||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help Makefile | ||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
import sys | ||
from pathlib import Path | ||
|
||
# Add source directory to path | ||
docs_dir = Path(__file__).parent | ||
project_root = docs_dir.parent | ||
sys.path.insert(0, str(project_root / "src")) | ||
|
||
# Project information | ||
project = "pipecat-ai" | ||
copyright = "2024, Daily" | ||
author = "Daily" | ||
|
||
# General configuration | ||
extensions = [ | ||
"sphinx.ext.autodoc", | ||
"sphinx.ext.napoleon", | ||
"sphinx.ext.viewcode", | ||
"sphinx.ext.intersphinx", | ||
] | ||
|
||
# Napoleon settings | ||
napoleon_google_docstring = True | ||
napoleon_numpy_docstring = False | ||
napoleon_include_init_with_doc = True | ||
|
||
# AutoDoc settings | ||
autodoc_default_options = { | ||
"members": True, | ||
"member-order": "bysource", | ||
"special-members": "__init__", | ||
"undoc-members": True, | ||
"exclude-members": "__weakref__", | ||
"no-index": True, | ||
} | ||
|
||
# HTML output settings | ||
html_theme = "sphinx_rtd_theme" | ||
html_static_path = ["_static"] | ||
autodoc_typehints = "description" | ||
html_show_sphinx = False # Remove "Built with Sphinx" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,104 @@ | ||
#!/usr/bin/env python3 | ||
|
||
import shutil | ||
import subprocess | ||
from pathlib import Path | ||
|
||
|
||
def run_command(command: list[str]) -> None: | ||
"""Run a command and exit if it fails.""" | ||
print(f"Running: {' '.join(command)}") | ||
try: | ||
subprocess.run(command, check=True) | ||
except subprocess.CalledProcessError as e: | ||
print(f"Warning: Command failed: {' '.join(command)}") | ||
print(f"Error: {e}") | ||
|
||
|
||
def main(): | ||
docs_dir = Path(__file__).parent | ||
project_root = docs_dir.parent.parent | ||
|
||
# Install documentation requirements | ||
requirements_file = docs_dir / "requirements.txt" | ||
run_command(["pip", "install", "-r", str(requirements_file)]) | ||
|
||
# Install from project root, not docs directory | ||
run_command(["pip", "install", "-e", str(project_root)]) | ||
|
||
# Install all service dependencies | ||
services = [ | ||
"anthropic", | ||
"assemblyai", | ||
"aws", | ||
"azure", | ||
"canonical", | ||
"cartesia", | ||
# "daily", | ||
"deepgram", | ||
"elevenlabs", | ||
"fal", | ||
"fireworks", | ||
"gladia", | ||
"google", | ||
"grok", | ||
"groq", | ||
"langchain", | ||
# "livekit", | ||
"lmnt", | ||
"moondream", | ||
"nim", | ||
"noisereduce", | ||
"openai", | ||
"openpipe", | ||
"playht", | ||
"silero", | ||
"soundfile", | ||
"websocket", | ||
"whisper", | ||
] | ||
|
||
extras = ",".join(services) | ||
try: | ||
run_command(["pip", "install", "-e", f"{str(project_root)}[{extras}]"]) | ||
except Exception as e: | ||
print(f"Warning: Some dependencies failed to install: {e}") | ||
|
||
# Clean old files | ||
api_dir = docs_dir / "api" | ||
build_dir = docs_dir / "_build" | ||
for dir in [api_dir, build_dir]: | ||
if dir.exists(): | ||
shutil.rmtree(dir) | ||
|
||
# Generate API documentation | ||
run_command( | ||
[ | ||
"sphinx-apidoc", | ||
"-f", # Force overwrite | ||
"-e", # Put each module on its own page | ||
"-M", # Put module documentation before submodule | ||
"--no-toc", # Don't generate modules.rst (cleaner structure) | ||
"-o", | ||
str(api_dir), # Output directory | ||
str(project_root / "src/pipecat"), | ||
# Exclude problematic files and directories | ||
str(project_root / "src/pipecat/processors/gstreamer"), # Optional gstreamer | ||
str(project_root / "src/pipecat/transports/network"), # Pydantic issues | ||
str(project_root / "src/pipecat/transports/services"), # Pydantic issues | ||
str(project_root / "src/pipecat/transports/local"), # Optional dependencies | ||
str(project_root / "src/pipecat/services/to_be_updated"), # Exclude to_be_updated | ||
"**/test_*.py", # Test files | ||
"**/tests/*.py", # Test files | ||
] | ||
) | ||
|
||
# Build HTML documentation | ||
run_command(["sphinx-build", "-b", "html", str(docs_dir), str(build_dir / "html")]) | ||
|
||
print("\nDocumentation generated successfully!") | ||
print(f"HTML docs: {build_dir}/html/index.html") | ||
|
||
|
||
if __name__ == "__main__": | ||
main() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,77 @@ | ||
Pipecat API Reference Docs | ||
========================== | ||
|
||
Welcome to Pipecat's API reference documentation! | ||
|
||
Pipecat is an open source framework for building voice and multimodal assistants. | ||
It provides a flexible pipeline architecture for connecting various AI services, | ||
audio processing, and transport layers. | ||
|
||
Quick Links | ||
----------- | ||
|
||
* `GitHub Repository <https://github.com/pipecat-ai/pipecat>`_ | ||
* `Website <https://pipecat.ai>`_ | ||
|
||
|
||
API Reference | ||
------------- | ||
|
||
Core Components | ||
~~~~~~~~~~~~~~~ | ||
|
||
* :mod:`pipecat.frames` | ||
* :mod:`pipecat.processors` | ||
* :mod:`pipecat.pipeline` | ||
|
||
Audio Processing | ||
~~~~~~~~~~~~~~~~ | ||
|
||
* :mod:`pipecat.audio` | ||
* :mod:`pipecat.vad` | ||
|
||
Services | ||
~~~~~~~~ | ||
|
||
* :mod:`pipecat.services` | ||
|
||
Transport & Serialization | ||
~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
* :mod:`pipecat.transports` | ||
* :mod:`pipecat.serializers` | ||
|
||
Utilities | ||
~~~~~~~~~ | ||
|
||
* :mod:`pipecat.clocks` | ||
* :mod:`pipecat.metrics` | ||
* :mod:`pipecat.sync` | ||
* :mod:`pipecat.transcriptions` | ||
* :mod:`pipecat.utils` | ||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
:caption: API Reference | ||
:hidden: | ||
|
||
api/pipecat.audio | ||
api/pipecat.clocks | ||
api/pipecat.frames | ||
api/pipecat.metrics | ||
api/pipecat.pipeline | ||
api/pipecat.processors | ||
api/pipecat.serializers | ||
api/pipecat.services | ||
api/pipecat.sync | ||
api/pipecat.transcriptions | ||
api/pipecat.transports | ||
api/pipecat.utils | ||
api/pipecat.vad | ||
|
||
Indices and tables | ||
================== | ||
|
||
* :ref:`genindex` | ||
* :ref:`modindex` | ||
* :ref:`search` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
@ECHO OFF | ||
|
||
pushd %~dp0 | ||
|
||
REM Command file for Sphinx documentation | ||
|
||
if "%SPHINXBUILD%" == "" ( | ||
set SPHINXBUILD=sphinx-build | ||
) | ||
set SOURCEDIR=. | ||
set BUILDDIR=_build | ||
|
||
%SPHINXBUILD% >NUL 2>NUL | ||
if errorlevel 9009 ( | ||
echo. | ||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx | ||
echo.installed, then set the SPHINXBUILD environment variable to point | ||
echo.to the full path of the 'sphinx-build' executable. Alternatively you | ||
echo.may add the Sphinx directory to PATH. | ||
echo. | ||
echo.If you don't have Sphinx installed, grab it from | ||
echo.https://www.sphinx-doc.org/ | ||
exit /b 1 | ||
) | ||
|
||
if "%1" == "" goto help | ||
|
||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
goto end | ||
|
||
:help | ||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% | ||
|
||
:end | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
sphinx>=8.1.3 | ||
sphinx-rtd-theme | ||
sphinx-markdown-builder | ||
sphinx-autodoc-typehints | ||
toml |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.