Merge pull request #1519 from pipecat-ai/mb/ref-docs-toc

Docs: Update ToC With Adapters and Observers

CONTRIBUTING.md

@@ -26,11 +26,52 @@ git commit -m "Description of your changes"
 git push origin your-branch-name
 ```
 
-9. **Submit a Pull Request (PR)**: Open a PR from your forked repository to the main branch of this repo. 
-> Important: Describe the changes you've made clearly!
+8. **Submit a Pull Request (PR)**: Open a PR from your forked repository to the main branch of this repo.
+   > Important: Describe the changes you've made clearly!
 
 Our maintainers will review your PR, and once everything is good, your contributions will be merged!
 
+## Code Style and Documentation
+
+### Python Code Style
+
+We use Ruff for code linting and formatting. Please ensure your code passes all linting checks before submitting a PR.
+
+### Docstring Conventions
+
+We follow Google-style docstrings with these specific conventions:
+
+- Class docstrings should fully document all parameters used in `__init__`
+- We don't require separate docstrings for `__init__` methods when parameters are documented in the class docstring
+- Property methods should have docstrings explaining their purpose and return value
+
+Example of correctly documented class:
+
+```python
+class MyClass:
+    """Class description.
+
+    Additional details about the class.
+
+    Args:
+        param1: Description of first parameter.
+        param2: Description of second parameter.
+    """
+
+    def __init__(self, param1, param2):
+        # No docstring required here as parameters are documented above
+        self.param1 = param1
+        self.param2 = param2
+
+    @property
+    def some_property(self) -> str:
+        """Get the formatted property value.
+
+        Returns:
+            A string representation of the property.
+        """
+        return f"Property: {self.param1}"
+```
 
 # Contributor Covenant Code of Conduct
 
@@ -51,23 +92,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -162,4 +203,4 @@ For answers to common questions about this code of conduct, see the FAQ at
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[translations]: https://www.contributor-covenant.org/translations

docs/api/index.rst

@@ -45,8 +45,10 @@ Transport & Serialization
 Utilities
 ~~~~~~~~~
 
+* :mod:`Adapters <pipecat.adapters>`
 * :mod:`Clocks <pipecat.clocks>`
 * :mod:`Metrics <pipecat.metrics>`
+* :mod:`Observers <pipecat.observers>`
 * :mod:`Sync <pipecat.sync>`
 * :mod:`Transcriptions <pipecat.transcriptions>`
 * :mod:`Utils <pipecat.utils>`
@@ -56,10 +58,12 @@ Utilities
    :caption: API Reference
    :hidden:
 
+   Adapters <api/pipecat.adapters>
    Audio <api/pipecat.audio>
    Clocks <api/pipecat.clocks>
    Frames <api/pipecat.frames>
    Metrics <api/pipecat.metrics>
+   Observers <api/pipecat.observers>
    Pipeline <api/pipecat.pipeline>
    Processors <api/pipecat.processors>
    Serializers <api/pipecat.serializers>

pyproject.toml

@@ -115,6 +115,9 @@ select = [
     "D", # Docstring rules
     "I", # Import rules
 ]
+# We ignore D107 because class docstrings already document __init__ parameters
+# and our Sphinx configuration uses napoleon_include_init_with_doc=True
+ignore = ["D107"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

src/pipecat/adapters/schemas/function_schema.py

@@ -8,16 +8,22 @@ from typing import Any, Dict, List
 
 
 class FunctionSchema:
+    """Standardized function schema representation for tool definition.
+
+    Provides a structured way to define function tools used with AI models like OpenAI.
+    This schema defines the function's name, description, parameter properties, and
+    required parameters, following specifications required by AI service providers.
+
+    Args:
+        name: Name of the function to be called.
+        description: Description of what the function does.
+        properties: Dictionary defining parameter types, descriptions, and constraints.
+        required: List of property names that are required parameters.
+    """
+
     def __init__(
         self, name: str, description: str, properties: Dict[str, Any], required: List[str]
     ) -> None:
-        """Standardized function schema representation.
-
-        :param name: Name of the function.
-        :param description: Description of the function.
-        :param properties: Dictionary defining properties types and descriptions.
-        :param required: List of required parameters.
-        """
         self._name = name
         self._description = description
         self._properties = properties
@@ -26,7 +32,8 @@ class FunctionSchema:
     def to_default_dict(self) -> Dict[str, Any]:
         """Converts the function schema to a dictionary.
 
-        :return: Dictionary representation of the function schema.
+        Returns:
+            Dictionary representation of the function schema.
         """
         return {
             "name": self._name,
@@ -40,16 +47,36 @@ class FunctionSchema:
 
     @property
     def name(self) -> str:
+        """Get the function name.
+
+        Returns:
+            The function name.
+        """
         return self._name
 
     @property
     def description(self) -> str:
+        """Get the function description.
+
+        Returns:
+            The function description.
+        """
         return self._description
 
     @property
     def properties(self) -> Dict[str, Any]:
+        """Get the function properties.
+
+        Returns:
+            Dictionary of parameter specifications.
+        """
         return self._properties
 
     @property
     def required(self) -> List[str]:
+        """Get the required parameters.
+
+        Returns:
+            List of required parameter names.
+        """
         return self._required