DOCS-1871: Update camera, encoder, gantry examples (#540)

Author: npentrel

src/viam/components/component_base.py

@@ -47,6 +47,14 @@ async def get_geometries(self, *, extra: Optional[Dict[str, Any]] = None, timeou
         """
         Get all geometries associated with the Component, in their current configuration, in the frame of the Component.
 
+        ::
+
+            geometries = await component.get_geometries()
+
+            if geometries:
+                # Get the center of the first geometry
+                print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")
+
         Returns:
             List[Geometry]: The geometries associated with the Component.
         """

src/viam/components/encoder/encoder.py

@@ -36,6 +36,14 @@ async def reset_position(
     ):
         """
         Set the current position to be the new zero (home) position.
+
+        ::
+
+            my_encoder = Encoder.from_robot(robot=robot, name='my_encoder')
+
+            # Reset the zero position of the encoder.
+            await my_encoder.reset_position()
+
         """
         ...
 
@@ -54,6 +62,14 @@ async def get_position(
         The position will be either in relative units (ticks away from a zero position) for
         ``PositionType.TICKS`` or absolute units (degrees along a circle) for ``PositionType.DEGREES``.
 
+        ::
+
+            my_encoder = Encoder.from_robot(robot=robot, name='my_encoder')
+
+            # Get the position of the encoder in ticks
+            position = await my_encoder.get_position(encoder.PositionTypeTicks)
+            print("The encoder position is currently ", position[0], position[1])
+
         Args:
             position_type (PositionType.ValueType): The desired output type of the position
 
@@ -75,6 +91,13 @@ async def get_properties(
         """
         Return a dictionary of the types of position reporting this encoder supports
 
+        ::
+
+            my_encoder = Encoder.from_robot(robot=robot, name='my_encoder')
+
+            # Get whether the encoder returns position in ticks or degrees.
+            properties = await my_encoder.get_properties()
+
         Returns:
             Encoder.Properties: Map of position types to supported status.
         """

src/viam/components/gantry/gantry.py

@@ -24,6 +24,13 @@ async def get_position(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
         """
         Get the position in millimeters.
 
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            # Get the current positions of the axes of the gantry in millimeters.
+            positions = await my_gantry.get_position()
+
         Returns:
             List[float]: The position of the axes.
         """
@@ -42,6 +49,20 @@ async def move_to_position(
         """
         Move the gantry to a new position at the requested speeds.
 
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            # Create a list of positions for the axes of the gantry to move to. Assume in
+            # this example that the gantry is multi-axis, with 3 axes.
+            examplePositions = [1, 2, 3]
+
+            exampleSpeeds = [3, 9, 12]
+
+            # Move the axes of the gantry to the positions specified.
+            await my_gantry.move_to_position(
+                positions=examplePositions, speeds=exampleSpeeds)
+
         Args:
             positions (List[float]): List of positions for the axes to move to,
                 in millimeters.
@@ -53,6 +74,12 @@ async def home(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optiona
         """
         Home the gantry to find it's starting and ending positions
 
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            await my_gantry.home()
+
         Returns:
             bool : whether the gantry has run the homing sequence successfully
         """
@@ -62,6 +89,13 @@ async def get_lengths(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
         """
         Get the lengths of the axes of the gantry in millimeters.
 
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            # Get the lengths of the axes of the gantry in millimeters.
+            lengths_mm = await my_gantry.get_lengths()
+
         Returns:
             List[float]: The lengths of the axes.
         """
@@ -71,6 +105,15 @@ async def get_lengths(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
     async def stop(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
         """
         Stop all motion of the gantry. It is assumed that the gantry stops immediately.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            # Stop all motion of the gantry. It is assumed that the gantry stops
+            # immediately.
+            await my_gantry.stop()
+
         """
         ...
 
@@ -79,6 +122,17 @@ async def is_moving(self) -> bool:
         """
         Get if the gantry is currently moving.
 
+        ::
+
+            my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
+
+            # Stop all motion of the gantry. It is assumed that the
+            # gantry stops immediately.
+            await my_gantry.stop()
+
+            # Print if the gantry is currently moving.
+            print(my_gantry.is_moving())
+
         Returns:
             bool: Whether the gantry is moving.
         """

src/viam/resource/base.py

@@ -45,6 +45,11 @@ def get_resource_name(cls, name: str) -> ResourceName:
     def from_robot(cls, robot: "RobotClient", name: str) -> Self:
         """Get the Resource named ``name`` from the provided robot.
 
+        ::
+
+            # Can be used with any resource, using an arm as an example
+            my_arm = Arm.from_robot(robot, "my_arm")
+
         Args:
             robot (RobotClient): The robot
             name (str): The name of the Resource
@@ -60,6 +65,11 @@ async def do_command(
     ) -> Mapping[str, "ValueTypes"]:
         """Send/Receive arbitrary commands to the Resource
 
+        ::
+
+            command = {"cmd": "test", "data1": 500}
+            result = component.do(command)
+
         Args:
             command (Mapping[str, ValueTypes]): The command to execute
 
@@ -92,5 +102,10 @@ async def close(self):
         Close must be idempotent. Later configuration may allow a resource to be "open" again.
         If a resource does not want or need a close function, it is assumed that the resource does not need to retun errors when future
         non-Close methods are called.
+
+        ::
+
+            await component.close()
+
         """
         return