From 44c5220104de8b70881b6114a18d4b5f2b3e853c Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Thu, 12 Dec 2024 13:28:05 -0500
Subject: [PATCH] Update README

---
 docs/api/README.md | 41 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/docs/api/README.md b/docs/api/README.md
index c0943653f..22b62d45e 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -10,15 +10,17 @@ This directory contains the source files for auto-generating Pipecat's server AP
 pip install -r requirements.txt
 ```
 
-2. Make the build script executable:
+2. Make the build scripts executable:
 
 ```bash
-chmod +x build-docs.sh
+chmod +x build-docs.sh rtd-test.py
 ```
 
 ## Building Documentation
 
-From this directory, run either:
+From this directory, you can build the documentation in several ways:
+
+### Local Build
 
 ```bash
 # Using the build script (automatically opens docs when done)
@@ -28,6 +30,24 @@ From this directory, run either:
 sphinx-build -b html . _build/html -W --keep-going
 ```
 
+### ReadTheDocs Test Build
+
+To test the documentation build process exactly as it would run on ReadTheDocs:
+
+```bash
+./rtd-test.py
+```
+
+This script:
+
+- Creates a fresh virtual environment
+- Installs all dependencies as specified in requirements files
+- Handles conflicting dependencies (like grpcio versions for Riva and PlayHT)
+- Builds the documentation in an isolated environment
+- Provides detailed logging of the build process
+
+Use this script to verify your documentation will build correctly on ReadTheDocs before pushing changes.
+
 ## Viewing Documentation
 
 The built documentation will be available at `_build/html/index.html`. To open:
@@ -52,8 +72,11 @@ start _build/html/index.html
 ├── _static/        # Static files (images, css, etc.)
 ├── conf.py         # Sphinx configuration
 ├── index.rst       # Main documentation entry point
-├── requirements.txt # Documentation dependencies
-└── build-docs.sh   # Build script matching ReadTheDocs configuration
+├── requirements-base.txt    # Base documentation dependencies
+├── requirements-riva.txt    # Riva-specific dependencies
+├── requirements-playht.txt  # PlayHT-specific dependencies
+├── build-docs.sh   # Local build script
+└── rtd-test.py     # ReadTheDocs test build script
 ```
 
 ## Notes
@@ -63,6 +86,7 @@ start _build/html/index.html
 - The build process matches our ReadTheDocs configuration
 - Warnings are treated as errors (-W flag) to maintain consistency
 - The --keep-going flag ensures all errors are reported
+- Dependencies are split into multiple requirements files to handle version conflicts
 
 ## Troubleshooting
 
@@ -71,6 +95,13 @@ If you encounter missing service modules:
 1. Verify the service is installed with its extras: `pip install pipecat-ai[service-name]`
 2. Check the build logs for import errors
 3. Ensure the service module is properly initialized in the package
+4. Run `./rtd-test.py` to test in an isolated environment matching ReadTheDocs
+
+For dependency conflicts:
+
+1. Check the requirements files for version specifications
+2. Use `rtd-test.py` to verify dependency resolution
+3. Consider adding service-specific requirements files if needed
 
 For more information: