docs(python-sdk): use google docstring format

CONTRIBUTING.md

@@ -29,6 +29,11 @@ We also expect new features added to have an associated test suite, which
 should be usable as documentation to understand the expectations of the new
 code.
 
+## Documentation
+
+In the python SDK, we document modules, functions, classes, and methods using
+docstrings. We use the [Google Docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
+
 ## Git workflow
 
 When creating a pull request with changes, please consider the following

docs/collections.md

@@ -206,14 +206,14 @@ my_deserialized_data = MyData(**data["my-data"])
 
 ## API Documentation
 
-## ::: numerous.collection.collection.collection
+## ::: numerous.collection.collection
     options:
         show_root_heading: true
 
-## ::: numerous.collection.numerous_collection.NumerousCollection
+## ::: numerous.collection.NumerousCollection
     options:
         show_root_heading: true
 
-## ::: numerous.collection.numerous_document.NumerousDocument
+## ::: numerous.collection.NumerousDocument
     options:
         show_root_heading: true

python/src/numerous/collection/collection.py

@@ -12,11 +12,18 @@ def collection(
     collection_key: str, _client: Optional[Client] = None
 ) -> NumerousCollection:
     """
-    Get or create a root collection by name.
+    Get or create a root collection by key.
 
     Use this function as an entry point to interact with collections.
+    If the collection does not exist, it is created.
+
+    Args:
+        collection_key: Key of the collection. A key is a string that uniquely
+            identifies a collection.
+
+    Returns:
+        The collection identified by the given key.
 
-    In cases where the collection doesn't exist, it will be created.
     """
     if _client is None:
         _client = get_client()

python/src/numerous/collection/numerous_collection.py

@@ -1,7 +1,7 @@
 """Class for working with numerous collections."""
 
 from dataclasses import dataclass
-from typing import Iterator, Optional
+from typing import Generator, Iterator, Optional
 
 from numerous.collection._client import Client
 from numerous.collection.numerous_document import NumerousDocument
@@ -22,7 +22,18 @@ def __init__(self, collection_ref: CollectionReference, _client: Client) -> None
         self._client = _client
 
     def collection(self, collection_key: str) -> "NumerousCollection":
-        """Get or create a collection by name."""
+        """
+        Get or create a child collection of this collection by key.
+
+        Args:
+            collection_key: Key of the nested collection. A key uniquely identifies a
+                collection within the parent collection. Keys are case sensitive, and
+                can be used as human-readable identifiers for collections
+
+        Returns:
+            NumerousCollection: The child collection identified by the given key.
+
+        """
         collection_ref = self._client.get_collection_reference(
             collection_key=collection_key, parent_collection_id=self.id
         )
@@ -36,9 +47,12 @@ def document(self, key: str) -> NumerousDocument:
         """
         Get or create a document by key.
 
-        Attributes
-        ----------
-        key (str): The key of the document.
+        Args:
+            key: Key of the document. A key uniquely identifies a document within its
+                collection. Keys are case sensitive.
+
+        Returns:
+            The document in the collection with the given key.
 
         """
         numerous_doc_ref = self._client.get_collection_document(self.id, key)
@@ -60,17 +74,14 @@ def documents(
         """
         Retrieve documents from the collection, filtered by a tag key and value.
 
-        Parameters
-        ----------
-        tag_key : Optional[str]
-            The key of the tag used to filter documents (optional).
-        tag_value : Optional[str]
-            The value of the tag used to filter documents (optional).
+        Args:
+            tag_key: If this and `tag_value` is specified, filter documents with this
+                tag.
+            tag_value: If this and `tag_key` is specified, filter documents with this
+                tag.
 
-        Yields
-        ------
-        NumerousDocument
-            Yields NumerousDocument objects from the collection.
+        Yields:
+            Documents from the collection.
 
         """
         end_cursor = ""
@@ -97,14 +108,12 @@ def documents(
                     numerous_doc_ref,
                 )
 
-    def collections(self) -> Iterator["NumerousCollection"]:
+    def collections(self) -> Generator["NumerousCollection", None, None]:
         """
         Retrieve nested collections from the collection.
 
-        Yields
-        ------
-        NumerousCollection
-            Yields NumerousCollection objects.
+        Yields:
+            Nested collections of this collection.
 
         """
         end_cursor = ""

python/src/numerous/collection/numerous_document.py

@@ -12,10 +12,9 @@ class NumerousDocument:
     """
     Represents a document in a Numerous collection.
 
-    Attributes
-    ----------
+    Attributes:
         key (str): The key of the document.
-        collection_info tuple[str, str]: The id
+        collection_info (tuple[str, str]): The id
             and key of collection document belongs to.
         data (Optional[dict[str, Any]]): The data of the document.
         id (Optional[str]): The unique identifier of the document.
@@ -65,11 +64,9 @@ def set(self, data: dict[str, Any]) -> None:
         Set the data for the document.
 
         Args:
-        ----
             data (dict[str, Any]): The data to set for the document.
 
         Raises:
-        ------
             ValueError: If the document data setting fails.
 
         """
@@ -88,12 +85,10 @@ def get(self) -> Optional[dict[str, Any]]:
         """
         Get the data of the document.
 
-        Returns
-        -------
+        Returns:
             dict[str, Any]: The data of the document.
 
-        Raises
-        ------
+        Raises:
             ValueError: If the document does not exist.
 
         """
@@ -107,8 +102,7 @@ def delete(self) -> None:
         """
         Delete the document.
 
-        Raises
-        ------
+        Raises:
             ValueError: If the document does not exist or deletion failed.
 
         """
@@ -131,12 +125,10 @@ def tag(self, key: str, value: str) -> None:
         Add a tag to the document.
 
         Args:
-        ----
             key (str): The tag key.
             value (str): The tag value.
 
         Raises:
-        ------
             ValueError: If the document does not exist.
 
         """
@@ -156,11 +148,9 @@ def tag_delete(self, tag_key: str) -> None:
         Delete a tag from the document.
 
         Args:
-        ----
             tag_key (str): The key of the tag to delete.
 
         Raises:
-        ------
             ValueError: If the document does not exist.
 
         """

python/src/numerous/experimental/marimo/_cookies/fastapi.py

@@ -21,16 +21,11 @@ def add_marimo_cookie_middleware(
     """
     Add a middleware that enables accessing cookies in marimo apps.
 
-    Parameters
-    ----------
-    app : FastAPI
-        The FastAPI app to add the middleware on.
-
-    session_ident : Optional[Callable[[], str]]
-        The identity function which must return a unique value for each session.
-
-    cookies_dir : Path | None
-        Path to the directory where cookies are stored.
+    Args:
+        app: The FastAPI app to add the middleware on.
+        session_ident: The identity function which must return a unique value for each
+            session.
+        cookies_dir: Path to the directory where cookies are stored.
 
     """
     cookies_dir = cookies_dir or Path(

python/src/numerous/experimental/marimo/_field.py

@@ -26,14 +26,12 @@ def _auto_label(key: str, label: Union[str, None]) -> str:
     Automatically assigns a label to a key if the label is None.
 
     Args:
-    ----
-        key (str): The key to be labeled.
-        label (str): The label to assign to the key. If None,
-            the key will be used as the label.
+        key: The key to be labeled.
+        label: The label to assign to the key. If None, the key will be used as the
+            label.
 
     Returns:
-    -------
-        str: The assigned label.
+        The assigned label.
 
     """
     if label is None:
@@ -56,12 +54,9 @@ def __init__(
         Field with a state that can be used in a Marimo app.
 
         Args:
-        ----
-            default (str | float, optional): The default value for the field.
-            Defaults to `...`.
-            annotation (type | None, optional): The type annotation for the field.
-            Defaults to None.
-            **kwargs (dict): Additional keyword arguments for the field.
+            default: The default value for the field.
+            annotation: The type annotation for the field.
+            kwargs: Additional keyword arguments for the field.
 
         """
         BaseField.__init__(self, default=default, annotation=annotation, **kwargs)
@@ -97,14 +92,11 @@ def slider(
         Create a slider UI element.
 
         Args:
-        ----
-            step (float, optional): The step size for the slider. Defaults to 1.
-            label (str | None, optional): The label for the slider. Defaults to None.
-            Defaults to None.
+            step: The step size for the slider.
+            label: The label for the slider.
 
         Returns:
-        -------
-            mo.ui.slider: The created slider UI element.
+            The created slider UI element.
 
         """
         return self._number_ui(mo.ui.slider, step, label)
@@ -118,15 +110,11 @@ def number(
         Create a number UI element.
 
         Args:
-        ----
-            step (float, optional): The step value for the number UI element.
-                Defaults to 1.
-            label (str, optional): The label for the number UI element.
-                Defaults to None.
+            step: The step value for the number UI element.
+            label: The label for the number UI element.
 
         Returns:
-        -------
-            mo.ui.number: The created number UI element.
+            The created number UI element.
 
         """
         number_ui = self._number_ui(mo.ui.number, step, label)
@@ -142,12 +130,10 @@ def text(self, label: Union[str, None] = None) -> mo.ui.text:
         Return a text field widget.
 
         Args:
-        ----
-            label (str, optional): The label for the text field. Defaults to None.
+            label: The label for the text field. Defaults to None.
 
         Returns:
-        -------
-            mo.ui.text: The text field widget.
+            The text field widget.
 
         """
         return mo.ui.text(
@@ -161,8 +147,7 @@ def set(self, value: Any) -> None:  # noqa: ANN401
         Set the value of the Marimo object.
 
         Args:
-        ----
-            value (int | str): The value to be set. It can be an integer or a string.
+            value: The value to be set. It can be an integer or a string.
 
         Overrides the set method to call the mo state set_value and then calls the super
         class's set method.