DOCS-1873: Add remaining component methods and imports (#543)

Author: npentrel

src/viam/components/arm/arm.py

@@ -14,6 +14,14 @@ class Arm(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     arm implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.arm import Arm
+        # To use move_to_position:
+        from viam.proto.common import Pose
+        # To use move_to_joint_positions:
+        from viam.proto.component.arm import JointPositions
     """
 
     SUBTYPE: Final = Subtype(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "arm")  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/base/base.py

@@ -15,6 +15,10 @@ class Base(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     base implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.base import Base
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/board/board.py

@@ -17,6 +17,10 @@ class Board(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     board implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.board import Board
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/camera/camera.py

@@ -25,6 +25,10 @@ class Camera(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     camera implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.camera import Camera
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/encoder/encoder.py

@@ -20,6 +20,10 @@ class Properties:
     This acts as an abstract base class for any drivers representing specific
     encoder implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.encoder import Encoder
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/gantry/gantry.py

@@ -13,6 +13,10 @@ class Gantry(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     gantry implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.gantry import Gantry
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/generic/generic.py

@@ -15,6 +15,10 @@ class Generic(ComponentBase):
     To create a Generic component (an arbitrary component that can process commands), this ``Generic`` component should be subclassed
     and the ``do_command`` function implemented.
 
+    ::
+
+        from viam.components.generic import Generic
+
     Example::
 
         class ComplexComponent(Generic):

src/viam/components/gripper/gripper.py

@@ -12,6 +12,10 @@ class Gripper(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     gripper implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.gripper import Gripper
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/input/input.py

@@ -135,6 +135,10 @@ class Controller(ComponentBase):
     Controller is a logical "container" more than an actual device
     Could be a single gamepad, or a collection of digitalInterrupts
     and analogReaders, a keyboard, etc.
+
+    ::
+
+        from viam.components.input import Control, Controller, EventType
     """
 
     SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]

src/viam/components/motor/motor.py

@@ -13,6 +13,10 @@ class Motor(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     motor implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.motor import Motor
     """
 
     @dataclass
@@ -36,6 +40,13 @@ async def set_power(
         Sets the "percentage" of power the motor should employ between -1 and 1.
         When ``power`` is negative, the rotation will be in the backward direction.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Set the power to 40% forwards.
+            await my_motor.set_power(power=0.4)
+
         Args:
             power (float): Power between -1 and 1
                 (negative implies backwards).
@@ -57,6 +68,13 @@ async def go_for(
         When ``rpm`` or ``revolutions`` is a negative value, the rotation will be in the backward direction.
         Note: if both ``rpm`` and ``revolutions`` are negative, the motor will spin in the forward direction.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Turn the motor 7.2 revolutions at 60 RPM.
+            await my_motor.go_for(rpm=60, revolutions=7.2)
+
         Args:
             rpm (float): Speed at which the motor should move in rotations per minute
                 (negative implies backwards).
@@ -81,6 +99,13 @@ async def go_to(
         Regardless of the directionality of the ``rpm`` this function will move
         the motor towards the specified position.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Turn the motor to 8.3 revolutions from home at 75 RPM.
+            await my_motor.go_to(rpm=75, revolutions=8.3)
+
         Args:
             rpm (float): Speed at which the motor should rotate (absolute value).
             position_revolutions (float): Target position relative to home/zero, in revolutions.
@@ -99,6 +124,13 @@ async def reset_zero_position(
         """
         Set the current position (modified by ``offset``) to be the new zero (home) position.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Set the current position as the new home position with no offset.
+            await my_motor.reset_zero_position(offset=0.0)
+
         Args:
             offset (float): The offset from the current position to new home/zero position.
         """
@@ -117,6 +149,13 @@ async def get_position(
         The value returned is the number of revolutions relative to its zero position.
         This method will raise an exception if position reporting is not supported by the motor.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Get the current position of the motor.
+            position = await my_motor.get_position()
+
         Returns:
             float: Number of revolutions the motor is away from zero/home.
         """
@@ -134,6 +173,17 @@ async def get_properties(
         Report a dictionary mapping optional properties to
         whether it is supported by this motor.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Report a dictionary mapping optional properties to whether it is supported by
+            # this motor.
+            properties = await my_motor.get_properties()
+
+            # Print out the properties.
+            print(f'Properties: {properties}')
+
         Returns:
             Properties: Map of feature names to supported status.
         """
@@ -149,6 +199,13 @@ async def stop(
     ):
         """
         Stop the motor immediately, without any gradual step down.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Stop the motor.
+            await my_motor.stop()
         """
         ...
 
@@ -163,6 +220,15 @@ async def is_powered(
         """
         Returns whether or not the motor is currently running.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Check whether the motor is currently running.
+            powered = await my_motor.is_powered()
+
+            print('Powered: ', powered)
+
         Returns:
             bool: Indicates whether the motor is currently powered.
             float: The current power percentage of the motor
@@ -174,6 +240,14 @@ async def is_moving(self) -> bool:
         """
         Get if the motor is currently moving.
 
+        ::
+
+            my_motor = Motor.from_robot(robot=robot, name="my_motor")
+
+            # Check whether the motor is currently moving.
+            moving = await my_motor.is_moving()
+            print('Moving: ', moving)
+
         Returns:
             bool: Whether the motor is moving.
         """