From abee0f853cf8e627a5249b44219df7131bcd1a22 Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Wed, 2 Jul 2025 13:57:57 -0700
Subject: [PATCH] Add deprecation directives, add indexing, only autodoc
 members

---
 CONTRIBUTING.md                               | 54 +++++++++----------
 docs/api/conf.py                              |  3 +-
 src/pipecat/pipeline/task.py                  |  4 ++
 .../audio/audio_buffer_processor.py           |  7 ++-
 src/pipecat/services/aws/tts.py               |  7 ++-
 src/pipecat/services/aws_nova_sonic/aws.py    |  2 +-
 src/pipecat/services/cartesia/tts.py          | 10 +++-
 src/pipecat/services/deepgram/stt.py          |  6 ++-
 src/pipecat/services/gladia/config.py         |  7 ++-
 src/pipecat/services/gladia/stt.py            |  3 ++
 src/pipecat/services/google/stt.py            |  2 +-
 src/pipecat/services/llm_service.py           |  4 ++
 src/pipecat/services/riva/stt.py              |  5 +-
 src/pipecat/services/riva/tts.py              |  5 +-
 src/pipecat/services/tts_service.py           |  4 ++
 src/pipecat/transports/base_transport.py      | 50 +++++++++++++++++
 src/pipecat/transports/services/daily.py      |  3 ++
 17 files changed, 132 insertions(+), 44 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bee07b8e0..2551ba6c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -86,6 +86,13 @@ We follow Google-style docstrings with these specific conventions:
 - Use section headers like "Supported features:" or "Behavior:" before lists
 - For complex nested information, consider using paragraph format instead
 
+**Deprecations:**
+
+- Use `warnings.warn()` in code for runtime deprecation warnings
+- Add `.. deprecated::` directive in docstrings for documentation visibility
+- Include version information and describe current status
+- Describe parameters in present tense, use directive to indicate deprecation status
+
 #### Examples:
 
 ```python
@@ -103,14 +110,24 @@ class MyService(BaseService):
     - Feature three for advanced use cases
     """
 
-    def __init__(self, param1: str, param2: bool = True, **kwargs):
+    def __init__(self, param1: str, old_param: str = None, **kwargs):
         """Initialize the service.
 
         Args:
             param1: Description of param1.
-            param2: Description of param2. Defaults to True.
+            old_param: Controls legacy behavior.
+
+                .. deprecated:: 1.2.0
+                    This parameter no longer has any effect and will be removed in version 2.0.
+
             **kwargs: Additional arguments passed to parent.
         """
+        if old_param is not None:
+            import warnings
+            warnings.warn(
+                "Parameter 'old_param' is deprecated and will be removed in version 2.0.",
+                DeprecationWarning,
+            )
         super().__init__(**kwargs)
 
     @property
@@ -133,21 +150,6 @@ class MyService(BaseService):
         """
         pass
 
-# Dataclass
-@dataclass
-class ConfigParams:
-    """Configuration parameters for the service.
-
-    Parameters:
-        host: The host address.
-        port: The port number. Defaults to 8080.
-        timeout: Connection timeout in seconds.
-    """
-
-    host: str
-    port: int = 8080
-    timeout: float = 30.0
-
 # Dataclass with code examples
 @dataclass
 class MessageFrame:
@@ -155,20 +157,12 @@ class MessageFrame:
 
     Supports both simple and content list message formats.
 
-    Examples:
-        Simple format::
+    Example::
 
-            [
-                {"role": "user", "content": "Hello"},
-                {"role": "assistant", "content": "Hi there!"}
-            ]
-
-        Content list format::
-
-            [
-                {"role": "user", "content": [{"type": "text", "text": "Hello"}]},
-                {"role": "assistant", "content": [{"type": "text", "text": "Hi there!"}]}
-            ]
+        [
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi there!"}
+        ]
 
     Parameters:
         messages: List of messages in OpenAI format.
diff --git a/docs/api/conf.py b/docs/api/conf.py
index 31c9fac25..1620341b9 100644
--- a/docs/api/conf.py
+++ b/docs/api/conf.py
@@ -38,9 +38,8 @@ napoleon_include_init_with_doc = True
 autodoc_default_options = {
     "members": True,
     "member-order": "bysource",
-    "undoc-members": True,
+    "undoc-members": False,
     "exclude-members": "__weakref__,model_config",
-    "no-index": True,
     "show-inheritance": True,
 }
 
diff --git a/src/pipecat/pipeline/task.py b/src/pipecat/pipeline/task.py
index a8b55e77c..2d3cfed77 100644
--- a/src/pipecat/pipeline/task.py
+++ b/src/pipecat/pipeline/task.py
@@ -76,6 +76,10 @@ class PipelineParams(BaseModel):
         heartbeats_period_secs: Period between heartbeats in seconds.
         interruption_strategies: Strategies for bot interruption behavior.
         observers: [deprecated] Use `observers` arg in `PipelineTask` class.
+
+            .. deprecated:: 0.0.58
+                Use the `observers` argument in the `PipelineTask` class instead.
+
         report_only_initial_ttfb: Whether to report only initial time to first byte.
         send_initial_empty_metrics: Whether to send initial empty metrics.
         start_metadata: Additional metadata for pipeline start.
diff --git a/src/pipecat/processors/audio/audio_buffer_processor.py b/src/pipecat/processors/audio/audio_buffer_processor.py
index 78561b2f9..97f36e3a6 100644
--- a/src/pipecat/processors/audio/audio_buffer_processor.py
+++ b/src/pipecat/processors/audio/audio_buffer_processor.py
@@ -70,7 +70,12 @@ class AudioBufferProcessor(FrameProcessor):
             sample_rate: Desired output sample rate. If None, uses source rate.
             num_channels: Number of channels (1 for mono, 2 for stereo). Defaults to 1.
             buffer_size: Size of buffer before triggering events. 0 for no buffering.
-            user_continuous_stream: Deprecated parameter for backwards compatibility.
+            user_continuous_stream: Controls whether user audio is treated as a continuous
+                stream for buffering purposes.
+
+                .. deprecated:: 0.0.72
+                    This parameter no longer has any effect and will be removed in a future version.
+
             enable_turn_audio: Whether turn audio event handlers should be triggered.
             **kwargs: Additional arguments passed to parent class.
         """
diff --git a/src/pipecat/services/aws/tts.py b/src/pipecat/services/aws/tts.py
index ce89dea9e..248d11210 100644
--- a/src/pipecat/services/aws/tts.py
+++ b/src/pipecat/services/aws/tts.py
@@ -343,7 +343,12 @@ class AWSPollyTTSService(TTSService):
 
 
 class PollyTTSService(AWSPollyTTSService):
-    """Deprecated alias for AWSPollyTTSService."""
+    """Deprecated alias for AWSPollyTTSService.
+
+    .. deprecated:: 0.0.67
+        `PollyTTSService` is deprecated, use `AWSPollyTTSService` instead.
+
+    """
 
     def __init__(self, **kwargs):
         """Initialize the deprecated PollyTTSService.
diff --git a/src/pipecat/services/aws_nova_sonic/aws.py b/src/pipecat/services/aws_nova_sonic/aws.py
index a7832669e..90c93fc39 100644
--- a/src/pipecat/services/aws_nova_sonic/aws.py
+++ b/src/pipecat/services/aws_nova_sonic/aws.py
@@ -151,7 +151,7 @@ class CurrentContent:
 class Params(BaseModel):
     """Configuration parameters for AWS Nova Sonic.
 
-    Attributes:
+    Parameters:
         input_sample_rate: Audio input sample rate in Hz.
         input_sample_size: Audio input sample size in bits.
         input_channel_count: Number of input audio channels.
diff --git a/src/pipecat/services/cartesia/tts.py b/src/pipecat/services/cartesia/tts.py
index 68cab0600..8d88179a5 100644
--- a/src/pipecat/services/cartesia/tts.py
+++ b/src/pipecat/services/cartesia/tts.py
@@ -98,7 +98,10 @@ class CartesiaTTSService(AudioContextWordTTSService):
         Parameters:
             language: Language to use for synthesis.
             speed: Voice speed control (string or float).
-            emotion: List of emotion controls (deprecated).
+            emotion: List of emotion controls.
+
+                .. deprecated:: 0.0.68
+                        The `emotion` parameter is deprecated and will be removed in a future version.
         """
 
         language: Optional[Language] = Language.EN
@@ -414,7 +417,10 @@ class CartesiaHttpTTSService(TTSService):
         Parameters:
             language: Language to use for synthesis.
             speed: Voice speed control (string or float).
-            emotion: List of emotion controls (deprecated).
+            emotion: List of emotion controls.
+
+                .. deprecated:: 0.0.68
+                        The `emotion` parameter is deprecated and will be removed in a future version.
         """
 
         language: Optional[Language] = Language.EN
diff --git a/src/pipecat/services/deepgram/stt.py b/src/pipecat/services/deepgram/stt.py
index d30e4da39..56658cad5 100644
--- a/src/pipecat/services/deepgram/stt.py
+++ b/src/pipecat/services/deepgram/stt.py
@@ -65,7 +65,11 @@ class DeepgramSTTService(STTService):
 
         Args:
             api_key: Deepgram API key for authentication.
-            url: Deprecated. Use base_url instead.
+            url: Custom Deepgram API base URL.
+
+                .. deprecated:: 0.0.64
+                    Parameter `url` is deprecated, use `base_url` instead.
+
             base_url: Custom Deepgram API base URL.
             sample_rate: Audio sample rate. If None, uses default or live_options value.
             live_options: Deepgram LiveOptions for detailed configuration.
diff --git a/src/pipecat/services/gladia/config.py b/src/pipecat/services/gladia/config.py
index 0af008773..09ed61bb0 100644
--- a/src/pipecat/services/gladia/config.py
+++ b/src/pipecat/services/gladia/config.py
@@ -153,7 +153,12 @@ class GladiaInputParams(BaseModel):
         custom_metadata: Additional metadata to include with requests
         endpointing: Silence duration in seconds to mark end of speech
         maximum_duration_without_endpointing: Maximum utterance duration without silence
-        language: DEPRECATED - Use language_config instead
+        language: Language code for transcription
+
+            .. deprecated:: 0.0.62
+                The 'language' parameter is deprecated and will be removed in a future version.
+                Use 'language_config' instead.
+
         language_config: Detailed language configuration
         pre_processing: Audio pre-processing options
         realtime_processing: Real-time processing features
diff --git a/src/pipecat/services/gladia/stt.py b/src/pipecat/services/gladia/stt.py
index f931993b3..a92fd5aef 100644
--- a/src/pipecat/services/gladia/stt.py
+++ b/src/pipecat/services/gladia/stt.py
@@ -189,6 +189,9 @@ class GladiaSTTService(STTService):
     Provides automatic reconnection, audio buffering, and comprehensive error handling.
 
     For complete API documentation, see: https://docs.gladia.io/api-reference/v2/live/init
+
+    .. deprecated:: 0.0.62
+        Use :class:`~pipecat.services.gladia.config.GladiaInputParams` directly instead.
     """
 
     # Maintain backward compatibility
diff --git a/src/pipecat/services/google/stt.py b/src/pipecat/services/google/stt.py
index 9cd2ac3ae..5e3e36e62 100644
--- a/src/pipecat/services/google/stt.py
+++ b/src/pipecat/services/google/stt.py
@@ -362,7 +362,7 @@ class GoogleSTTService(STTService):
     with streaming support. Handles audio transcription and optional voice activity detection.
     Implements automatic stream reconnection to handle Google's 4-minute streaming limit.
 
-    Attributes:
+    Parameters:
         InputParams: Configuration parameters for the STT service.
         STREAMING_LIMIT: Google Cloud's streaming limit in milliseconds (4 minutes).
 
diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py
index 669a34803..cc4cd3916 100644
--- a/src/pipecat/services/llm_service.py
+++ b/src/pipecat/services/llm_service.py
@@ -273,6 +273,10 @@ class LLMService(AIService):
                 parameter.
             start_callback: Legacy callback function (deprecated). Put initialization
                 code at the top of your handler instead.
+
+                .. deprecated:: 0.0.59
+                    The `start_callback` parameter is deprecated and will be removed in a future version.
+
             cancel_on_interruption: Whether to cancel this function call when an
                 interruption occurs. Defaults to True.
         """
diff --git a/src/pipecat/services/riva/stt.py b/src/pipecat/services/riva/stt.py
index a7d114a12..23cff7c5e 100644
--- a/src/pipecat/services/riva/stt.py
+++ b/src/pipecat/services/riva/stt.py
@@ -660,8 +660,9 @@ class RivaSegmentedSTTService(SegmentedSTTService):
 class ParakeetSTTService(RivaSTTService):
     """Deprecated speech-to-text service using NVIDIA Parakeet models.
 
-    This class is deprecated. Use RivaSTTService instead for equivalent functionality
-    with Parakeet models by specifying the appropriate model_function_map.
+    .. deprecated:: 0.0.66
+        This class is deprecated. Use `RivaSTTService` instead for equivalent functionality
+        with Parakeet models by specifying the appropriate model_function_map.
     """
 
     def __init__(
diff --git a/src/pipecat/services/riva/tts.py b/src/pipecat/services/riva/tts.py
index b75f09db0..6e5937c6f 100644
--- a/src/pipecat/services/riva/tts.py
+++ b/src/pipecat/services/riva/tts.py
@@ -188,8 +188,9 @@ class RivaTTSService(TTSService):
 class FastPitchTTSService(RivaTTSService):
     """Deprecated FastPitch TTS service.
 
-    This class is deprecated. Use RivaTTSService instead for new implementations.
-    Provides backward compatibility for existing FastPitch TTS integrations.
+    .. deprecated:: 0.0.66
+        This class is deprecated. Use RivaTTSService instead for new implementations.
+        Provides backward compatibility for existing FastPitch TTS integrations.
     """
 
     def __init__(
diff --git a/src/pipecat/services/tts_service.py b/src/pipecat/services/tts_service.py
index 43ab5634f..62fcdd4e6 100644
--- a/src/pipecat/services/tts_service.py
+++ b/src/pipecat/services/tts_service.py
@@ -94,6 +94,10 @@ class TTSService(AIService):
             text_aggregator: Custom text aggregator for processing incoming text.
             text_filters: Sequence of text filters to apply after aggregation.
             text_filter: Single text filter (deprecated, use text_filters).
+
+                .. deprecated:: 0.0.59
+                    Use `text_filters` instead, which allows multiple filters.
+
             transport_destination: Destination for generated audio frames.
             **kwargs: Additional arguments passed to the parent AIService.
         """
diff --git a/src/pipecat/transports/base_transport.py b/src/pipecat/transports/base_transport.py
index 8e722127f..b48cec02d 100644
--- a/src/pipecat/transports/base_transport.py
+++ b/src/pipecat/transports/base_transport.py
@@ -29,13 +29,53 @@ class TransportParams(BaseModel):
 
     Parameters:
         camera_in_enabled: Enable camera input (deprecated, use video_in_enabled).
+
+            .. deprecated:: 0.0.66
+               The `camera_in_enabled` parameter is deprecated, use
+               `video_in_enabled` instead.
+
         camera_out_enabled: Enable camera output (deprecated, use video_out_enabled).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_enabled` parameter is deprecated, use
+               `video_out_enabled` instead.
+
         camera_out_is_live: Enable real-time camera output (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_is_live` parameter is deprecated, use
+               `video_out_is_live` instead.
+
         camera_out_width: Camera output width in pixels (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `camera_out_width` parameter is deprecated, use
+               `video_out_width` instead.
+
         camera_out_height: Camera output height in pixels (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_height` parameter is deprecated, use
+                `video_out_height` instead.
+
         camera_out_bitrate: Camera output bitrate in bits per second (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_bitrate` parameter is deprecated, use
+                `video_out_bitrate` instead.
+
         camera_out_framerate: Camera output frame rate in FPS (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_framerate` parameter is deprecated, use
+                `video_out_framerate` instead.
+
         camera_out_color_format: Camera output color format string (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `camera_out_color_format` parameter is deprecated, use
+                `video_out_color_format` instead.
+
         audio_out_enabled: Enable audio output streaming.
         audio_out_sample_rate: Output audio sample rate in Hz.
         audio_out_channels: Number of output audio channels.
@@ -59,7 +99,17 @@ class TransportParams(BaseModel):
         video_out_color_format: Video output color format string.
         video_out_destinations: List of video output destination identifiers.
         vad_enabled: Enable Voice Activity Detection (deprecated).
+
+            .. deprecated:: 0.0.66
+               The `vad_enabled` parameter is deprecated, use `audio_in_enabled`
+               and `TransportParams.vad_analyzer` instead.
+
         vad_audio_passthrough: Enable VAD audio passthrough (deprecated).
+
+            .. deprecated:: 0.0.66
+                The `vad_audio_passthrough` parameter is deprecated, use `audio_in_passthrough`
+                instead.
+
         vad_analyzer: Voice Activity Detection analyzer instance.
         turn_analyzer: Turn-taking analyzer instance for conversation management.
     """
diff --git a/src/pipecat/transports/services/daily.py b/src/pipecat/transports/services/daily.py
index a404f7648..fdbca6643 100644
--- a/src/pipecat/transports/services/daily.py
+++ b/src/pipecat/transports/services/daily.py
@@ -1977,6 +1977,9 @@ class DailyTransport(BaseTransport):
     async def send_dtmf(self, settings):
         """Send DTMF tones during a call (deprecated).
 
+        .. deprecated:: 0.0.69
+            Push an `OutputDTMFFrame` or an `OutputDTMFUrgentFrame` instead.
+
         Args:
             settings: DTMF settings including tones and target session.
         """