DOCS-1875: Add generic and ViamClient examples (#558)

Author: skyleilani

src/viam/app/viam_client.py

@@ -16,6 +16,7 @@
 class ViamClient:
     """gRPC client for all communication and interaction with app.
 
+    `ViamClient` class for creating and managing specialized client instances.
     There is currently 1 way to instantiate a `ViamClient` object::
 
         ViamClient.create_from_dial_options(...)
@@ -25,10 +26,14 @@ class ViamClient:
     async def create_from_dial_options(cls, dial_options: DialOptions, app_url: Optional[str] = None) -> Self:
         """Create `ViamClient` that establishes a connection to the Viam app.
 
-        Args:
+        ::
+
+            dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+            ViamClient.create_from_dial_options(dial_options)
 
-            dial_options (viam.rpc.dial.DialOptions): Required information for authorization and connection to app. `creds` and
-                `auth_entity` fields are required.
+        Args:
+            dial_options (viam.rpc.dial.DialOptions): Required information for authorization and connection to app.
+                `creds` and `auth_entity` fields are required.
             app_url: (Optional[str]): URL of app. Uses app.viam.com if not specified.
 
         Raises:
@@ -62,22 +67,70 @@ async def create_from_dial_options(cls, dial_options: DialOptions, app_url: Opti
 
     @property
     def data_client(self) -> DataClient:
-        """Insantiate and return a `DataClient` used to make `data` and `data_sync` method calls."""
+        """Instantiate and return a `DataClient` object used to make `data` and `data_sync` method calls.
+        To use the `DataClient`, you must first instantiate a `ViamClient`.
+
+        ::
+
+            async def connect() -> ViamClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                return await ViamClient.create_from_dial_options(dial_options)
+
+            async def main():
+                viam_client = await connect()
+
+                # Instantiate a DataClient to run data client API methods on
+                data_client = viam_client.data_client
+        """
         return DataClient(self._channel, self._metadata)
 
     @property
     def app_client(self) -> AppClient:
-        """Insantiate and return an `AppClient` used to make  `app` method calls."""
+        """Instantiate and return an `AppClient` used to make  `app` method calls.
+        To use the `AppClient`, you must first instantiate a `ViamClient`.
+
+        ::
+
+            async def connect() -> ViamClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                return await ViamClient.create_from_dial_options(dial_options)
+
+
+            async def main():
+                viam_client = await connect()
+
+                # Instantiate an AppClient called "fleet" to run fleet management API methods on
+                fleet = viam_client.app_client
+        """
         return AppClient(self._channel, self._metadata, self._location_id)
 
     @property
     def ml_training_client(self) -> MLTrainingClient:
-        """Instantiate and return a `MLTrainingClient` used to make `ml_training` method calls."""
+        """Instantiate and return a `MLTrainingClient` used to make `ml_training` method calls.
+        To use the `MLTrainingClient`, you must first instantiate a `ViamClient`.
+
+        ::
+
+            async def connect() -> ViamClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                return await ViamClient.create_from_dial_options(dial_options)
+
+
+            async def main():
+                viam_client = await connect()
+
+                # Instantiate an MLTrainingClient to run ML training client API methods on
+                ml_training_client = viam_client.ml_training_client
+        """
         return MLTrainingClient(self._channel, self._metadata)
 
     @property
     def billing_client(self) -> BillingClient:
-        """Instantiate and return a `BillingClient` used to make `billing` method calls."""
+        """Instantiate and return a `BillingClient` used to make `billing` method calls.
+            To use the `BillingClient`, you must first instantiate a `ViamClient`."""
         return BillingClient(self._channel, self._metadata)
 
     def close(self):

src/viam/services/service_base.py

@@ -25,6 +25,21 @@ def __init__(self, name: str) -> None:
     def from_robot(cls, robot: "RobotClient", name: str) -> Self:
         """Get the service named ``name`` from the provided robot.
 
+        ::
+
+            async def connect() -> ViamClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                return await ViamClient.create_from_dial_options(dial_options)
+
+            async def main():
+                robot = await connect()
+
+                # Can be used with any resource, using the motion service as an example
+                motion = MotionClient.from_robot(robot=robot, name="builtin")
+
+                robot.close()
+
         Args:
             robot (RobotClient): The robot
             name (str): The name of the service
@@ -36,7 +51,19 @@ def from_robot(cls, robot: "RobotClient", name: str) -> Self:
         return cast(cls, service)
 
     async def do_command(self, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, ValueTypes]:
-        """Send/receive arbitrary commands
+        """Send/receive arbitrary commands.
+
+        ::
+
+            motion = MotionClient.from_robot(robot, "builtin")
+
+            my_command = {
+              "cmnd": "dosomething",
+              "someparameter": 52
+            }
+
+            # Can be used with any resource, using the motion service as an example
+            await motion.do_command(command=my_command)
 
         Args:
             command (Dict[str, ValueTypes]): The command to execute