DOCS-2313: Clean up gantry, camera, board, encoder and arm pages for docs parsing (#631)

Author: sguequierre

src/viam/components/arm/arm.py

@@ -35,7 +35,7 @@ async def get_end_position(
         **kwargs,
     ) -> Pose:
         """
-        Get the current position of the end of the arm expressed as a Pose.
+        Get the current position of the end of the arm expressed as a ``Pose``.
 
         ::
 
@@ -45,7 +45,10 @@ async def get_end_position(
             pos = await my_arm.get_end_position()
 
         Returns:
-            Pose: The location and orientation of the arm described as a Pose.
+            Pose: A representation of the arm’s current position as a 6 DOF (six degrees of freedom) pose.
+            The ``Pose`` is composed of values for location and orientation with respect to the origin.
+            Location is expressed as distance, which is represented by x, y, and z coordinate values.
+            Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.
         """
         ...
 
@@ -72,7 +75,10 @@ async def move_to_position(
             await my_arm.move_to_position(pose=examplePose)
 
         Args:
-            pose (Pose): The destination Pose for the arm.
+            pose (Pose): The destination ``Pose`` for the arm. The ``Pose`` is composed of values for location and orientation
+                with respect to the origin.
+                Location is expressed as distance, which is represented by x, y, and z coordinate values.
+                Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.
         """
         ...
 
@@ -127,7 +133,9 @@ async def get_joint_positions(
             pos = await my_arm.get_joint_positions()
 
         Returns:
-            JointPositions: The current JointPositions for the arm.
+            JointPositions: The current ``JointPositions`` for the arm.
+            ``JointPositions`` can have one attribute, ``values``, a list of joint positions with rotational values (degrees)
+            and translational values (mm).
         """
         ...
 
@@ -148,6 +156,7 @@ async def stop(
 
             # Stop all motion of the arm. It is assumed that the arm stops immediately.
             await my_arm.stop()
+
         """
         ...
 
@@ -193,7 +202,7 @@ async def get_kinematics(
 
         Returns:
             Tuple[KinematicsFileFormat.ValueType, bytes]: A tuple containing two values; the first [0] value represents the format of the
-                file, either in URDF format or Viam's kinematic parameter format (spatial vector algebra), and the second [1] value
-                represents the byte contents of the file.
+            file, either in URDF format or Viam's kinematic parameter format (spatial vector algebra), and the second [1] value
+            represents the byte contents of the file.
         """
         ...

src/viam/components/board/board.py

@@ -38,7 +38,7 @@ class Board(ComponentBase):
 
     class Analog:
         """
-        AnalogReader represents an analog pin reader or writer that resides on a Board.
+        Analog represents an analog pin reader or writer that resides on a Board.
         """
 
         name: str
@@ -63,7 +63,7 @@ async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optiona
 
                 my_board = Board.from_robot(robot=robot, name="my_board")
 
-                # Get the AnalogReader "my_example_analog_reader".
+                # Get the Analog "my_example_analog_reader".
                 reader = await my_board.analog_reader_by_name(
                     name="my_example_analog_reader")
 
@@ -79,16 +79,20 @@ async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optiona
         @abc.abstractmethod
         async def write(self, value: int, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
             """
-            Write a value to the analog writer.
+            Write a value to the Analog writer.
 
             ::
+
                 my_board = Board.from_robot(robot=robot, name="my_board")
 
-                # Get the AnalogWriter "my_example_analog_writer".
+                # Get the Analog "my_example_analog_writer".
                 writer = await my_board.analog_by_name(
                     name="my_example_analog_writer")
 
                 await writer.write(42)
+
+            Args:
+                value (int): Value to write to the analog writer.
             """
             ...
 
@@ -100,7 +104,7 @@ class DigitalInterrupt:
         """
 
         name: str
-        """The name of the digital interrupt"""
+        """The name of the digital interrupt."""
 
         def __init__(self, name: str):
             self.name = name
@@ -130,11 +134,11 @@ async def value(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Option
 
     class GPIOPin:
         """
-        Abstract representation of an individual GPIO pin on a board
+        Abstract representation of an individual GPIO pin on a board.
         """
 
         name: str
-        """The name of the GPIO pin"""
+        """The name of the GPIO pin."""
 
         def __init__(self, name: str):
             self.name = name

src/viam/components/camera/camera.py

@@ -59,7 +59,7 @@ async def get_image(
             mime_type (str): The desired mime type of the image. This does not guarantee output type
 
         Returns:
-            ViamImage: The frame
+            ViamImage: The frame.
         """
         ...
 
@@ -77,8 +77,8 @@ async def get_images(self, *, timeout: Optional[float] = None, **kwargs) -> Tupl
             timestamp = metadata.captured_at
 
         Returns:
-            Tuple[List[NamedImage], ResponseMetadata]: A tuple containing two values; the first [0] a list of images returned from the
-                camera system, and the second [1] the metadata associated with this response.
+            Tuple[List[NamedImage], ResponseMetadata]: A tuple containing two values; the first [0] a list of images
+            returned from the camera system, and the second [1] the metadata associated with this response.
         """
         ...
 
@@ -108,8 +108,8 @@ async def get_point_cloud(
             points = np.asarray(pcd.points)
 
         Returns:
-            Tuple[bytes, str]: A tuple containing two values; the first [0] the pointcloud data, and the second [1] the mimetype of the
-                pointcloud (e.g. PCD).
+            Tuple[bytes, str]: A tuple containing two values; the first [0] the pointcloud data,
+            and the second [1] the mimetype of the pointcloud (for example, PCD).
         """
         ...
 
@@ -125,6 +125,6 @@ async def get_properties(self, *, timeout: Optional[float] = None, **kwargs) ->
             properties = await my_camera.get_properties()
 
         Returns:
-            Properties: The properties of the camera
+            Properties: The properties of the camera.
         """
         ...

src/viam/components/encoder/encoder.py

@@ -75,12 +75,12 @@ async def get_position(
             print("The encoder position is currently ", position[0], position[1])
 
         Args:
-            position_type (PositionType.ValueType): The desired output type of the position
+            position_type (PositionType.ValueType): The desired output type of the position.
 
         Returns:
-            Tuple[float, PositionType]: A tuple containing two values; the first [0] the Position of the encoder which can either be
-                ticks since last zeroing for a relative encoder or degrees for an absolute encoder, and the second [1] the type of
-                position the encoder returns (ticks or degrees).
+            Tuple[float, PositionType]: A tuple containing two values; the first [0] the Position of the encoder
+            which can either be ticks since last zeroing for a relative encoder or degrees for an absolute encoder,
+            and the second [1] the type of position the encoder returns (ticks or degrees).
         """
         ...
 

src/viam/components/gantry/gantry.py

@@ -26,7 +26,7 @@ class Gantry(ComponentBase):
     @abc.abstractmethod
     async def get_position(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[float]:
         """
-        Get the position in millimeters.
+        Get the positions of the axes of the gantry in millimeters.
 
         ::
 
@@ -36,7 +36,7 @@ async def get_position(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
             positions = await my_gantry.get_position()
 
         Returns:
-            List[float]: The position of the axes.
+            List[float]: A list of the position of the axes of the gantry in millimeters.
         """
         ...
 
@@ -51,7 +51,7 @@ async def move_to_position(
         **kwargs,
     ):
         """
-        Move the gantry to a new position at the requested speeds.
+        Move the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
 
         ::
 
@@ -68,15 +68,15 @@ async def move_to_position(
                 positions=examplePositions, speeds=exampleSpeeds)
 
         Args:
-            positions (List[float]): List of positions for the axes to move to,
-                in millimeters.
+            positions (List[float]): A list of positions for the axes of the gantry to move to, in millimeters.
+            speeds (List[float]): A list of speeds in millimeters per second for the gantry to move at respective to each axis.
         """
         ...
 
     @abc.abstractmethod
     async def home(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> bool:
         """
-        Home the gantry to find it's starting and ending positions
+        Run the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
 
         ::
 
@@ -85,7 +85,7 @@ async def home(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optiona
             await my_gantry.home()
 
         Returns:
-            bool : whether the gantry has run the homing sequence successfully
+            bool: Whether the gantry has run the homing sequence successfully.
         """
 
     @abc.abstractmethod
@@ -101,7 +101,7 @@ async def get_lengths(self, *, extra: Optional[Dict[str, Any]] = None, timeout:
             lengths_mm = await my_gantry.get_lengths()
 
         Returns:
-            List[float]: The lengths of the axes.
+            List[float]: A list of the lengths of the axes of the gantry in millimeters.
         """
         ...