docs: add usage examples and docs

airbyte/cloud/connectors.py

@@ -1,5 +1,41 @@
 # Copyright (c) 2024 Airbyte, Inc., all rights reserved.
-"""Cloud connectors module for working with Cloud sources and destinations."""
+"""Cloud connectors module for working with Cloud sources and destinations.
+
+This module provides classes for working with Cloud sources and destinations. Rather
+than creating `CloudConnector` objects directly, it is recommended to use the
+`airbyte.cloud.workspaces` module to create and manage cloud connector objects.
+
+Classes:
+  - `CloudConnector`: A cloud connector object.
+  - `CloudSource`: A cloud source object.
+  - `CloudDestination`: A cloud destination object.
+
+## Usage Examples
+
+Obtain a cloud source object and run a `check` on it:
+
+```python
+from airbyte.cloud import CloudWorkspace
+
+workspace = CloudWorkspace(
+    workspace_id="...",
+    client_id="...",
+    client_secret="...",
+)
+
+# Get the cloud source object
+cloud_source = workspace.get_source("...")
+
+# Check the source configuration and credentials
+check_result = cloud_source.check()
+if check_result:
+    # Truthy if the check was successful
+    print("Check successful")
+else:
+    # Stringify the check result to get the error message
+    print(f"Check failed: {check_result}")
+```
+"""
 
 from __future__ import annotations
 

airbyte/cloud/workspaces.py

@@ -3,6 +3,34 @@
 
 By overriding `api_root`, you can use this module to interact with self-managed Airbyte instances,
 both OSS and Enterprise.
+
+## Usage Examples
+
+Get a new workspace object and deploy a source to it:
+
+```python
+import airbyte as ab
+from airbyte import cloud
+
+workspace = cloud.CloudWorkspace(
+    workspace_id="...",
+    client_id="...",
+    client_secret="...",
+)
+
+# Deploy a source to the workspace
+source = ab.get_source("source-faker", config={"count": 100})
+deployed_source = workspace.deploy_source(
+    name="test-source",
+    source=source,
+)
+
+# Run a check on the deployed source and raise an exception if the check fails
+check_result = deployed_source.check(raise_on_error=True)
+
+# Permanently delete the newly-created source
+workspace.permanently_delete_source(deployed_source)
+```
 """
 
 from __future__ import annotations