Python API docs (#614)

* Python API docs working

* Python API doc generation

trustgraph-base/trustgraph/api/collection.py

@@ -1,3 +1,11 @@
+"""
+TrustGraph Collection Management
+
+This module provides interfaces for managing data collections in TrustGraph.
+Collections provide logical grouping and isolation for documents and knowledge
+graph data.
+"""
+
 import datetime
 import logging
 
@@ -7,14 +15,71 @@ from . exceptions import *
 logger = logging.getLogger(__name__)
 
 class Collection:
+    """
+    Collection management client.
+
+    Provides methods for managing data collections, including listing,
+    updating metadata, and deleting collections. Collections organize
+    documents and knowledge graph data into logical groupings for
+    isolation and access control.
+    """
 
     def __init__(self, api):
+        """
+        Initialize Collection client.
+
+        Args:
+            api: Parent Api instance for making requests
+        """
         self.api = api
 
     def request(self, request):
+        """
+        Make a collection-scoped API request.
+
+        Args:
+            request: Request payload dictionary
+
+        Returns:
+            dict: Response object
+        """
         return self.api.request(f"collection-management", request)
 
     def list_collections(self, user, tag_filter=None):
+        """
+        List all collections for a user.
+
+        Retrieves metadata for all collections owned by the specified user,
+        with optional filtering by tags.
+
+        Args:
+            user: User identifier
+            tag_filter: Optional list of tags to filter collections (default: None)
+
+        Returns:
+            list[CollectionMetadata]: List of collection metadata objects
+
+        Raises:
+            ProtocolException: If response format is invalid
+
+        Example:
+            ```python
+            collection = api.collection()
+
+            # List all collections
+            all_colls = collection.list_collections(user="trustgraph")
+            for coll in all_colls:
+                print(f"{coll.collection}: {coll.name}")
+                print(f"  Description: {coll.description}")
+                print(f"  Tags: {', '.join(coll.tags)}")
+
+            # List collections with specific tags
+            research_colls = collection.list_collections(
+                user="trustgraph",
+                tag_filter=["research", "published"]
+            )
+            ```
+        """
 
         input = {
             "operation": "list-collections",
@@ -50,6 +115,46 @@ class Collection:
             raise ProtocolException(f"Response not formatted correctly")
 
     def update_collection(self, user, collection, name=None, description=None, tags=None):
+        """
+        Update collection metadata.
+
+        Updates the name, description, and/or tags for an existing collection.
+        Only provided fields are updated; others remain unchanged.
+
+        Args:
+            user: User identifier
+            collection: Collection identifier
+            name: New collection name (optional)
+            description: New collection description (optional)
+            tags: New list of tags (optional)
+
+        Returns:
+            CollectionMetadata: Updated collection metadata, or None if not found
+
+        Raises:
+            ProtocolException: If response format is invalid
+
+        Example:
+            ```python
+            collection_api = api.collection()
+
+            # Update collection metadata
+            updated = collection_api.update_collection(
+                user="trustgraph",
+                collection="default",
+                name="Default Collection",
+                description="Main data collection for general use",
+                tags=["default", "production"]
+            )
+
+            # Update only specific fields
+            updated = collection_api.update_collection(
+                user="trustgraph",
+                collection="research",
+                description="Updated description"
+            )
+            ```
+        """
 
         input = {
             "operation": "update-collection",
@@ -82,6 +187,29 @@ class Collection:
             raise ProtocolException(f"Response not formatted correctly")
 
     def delete_collection(self, user, collection):
+        """
+        Delete a collection.
+
+        Removes a collection and all its associated data from the system.
+
+        Args:
+            user: User identifier
+            collection: Collection identifier to delete
+
+        Returns:
+            dict: Empty response object
+
+        Example:
+            ```python
+            collection_api = api.collection()
+
+            # Delete a collection
+            collection_api.delete_collection(
+                user="trustgraph",
+                collection="old-collection"
+            )
+            ```
+        """
 
         input = {
             "operation": "delete-collection",