RSDK-398, RSDK-861: Some documentation fixes (#187)

Author: cheukt

src/viam/components/arm/arm.py

@@ -13,8 +13,8 @@ class Arm(ComponentBase):
     Arm represents a physical robot arm that exists in three-dimensional space.
 
     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.
+    arm implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
     """
 
     @abc.abstractmethod
@@ -43,14 +43,14 @@ async def move_to_position(
         **kwargs,
     ):
         """
-        Move the end of the arm to the Pose specified in `pose`.
-        When obstacles are specified in `world_state`, the motion plan of the arm will avoid them.
+        Move the end of the arm to the Pose specified in ``pose``.
+        When obstacles are specified in ``world_state``, the motion plan of the arm will avoid them.
 
         Args:
 
             pose (Pose): The destination Pose for the arm.
 
-            world_state (WorldState): The obstacles for the arm to avoid on its way to `pose`.
+            world_state (WorldState): The obstacles for the arm to avoid on its way to ``pose``.
         """
         ...
 
@@ -64,11 +64,11 @@ async def move_to_joint_positions(
         **kwargs,
     ):
         """
-        Move each joint on the arm to the corresponding angle specified in `positions`.
+        Move each joint on the arm to the corresponding angle specified in ``positions``.
 
         Args:
 
-            positions (JointPositions): The destination `JointPositions` for the arm.
+            positions (JointPositions): The destination ``JointPositions`` for the arm.
         """
         ...
 

src/viam/components/arm/client.py

@@ -23,7 +23,7 @@ class ArmClient(Arm):
     """
     gRPC client for an Arm component.
 
-    Used to communicate with an existing `Arm` implementation over gRPC.
+    Used to communicate with an existing ``Arm`` implementation over gRPC.
     """
 
     def __init__(self, name: str, channel: Channel):

src/viam/components/base/base.py

@@ -12,8 +12,8 @@ class Base(ComponentBase):
     Base represents a physical base of a robot.
 
     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.
+    base implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
     """
 
     @abc.abstractmethod
@@ -27,9 +27,9 @@ async def move_straight(
         **kwargs,
     ):
         """
-        Move the base in a straight line the given `distance`, expressed in millimeters,
-        at the given `velocity`, expressed in millimeters per second.
-        When `distance` or `velocity` is 0, the base will stop.
+        Move the base in a straight line the given ``distance``, expressed in millimeters,
+        at the given ``velocity``, expressed in millimeters per second.
+        When ``distance`` or ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
         Args:
@@ -51,9 +51,9 @@ async def spin(
         **kwargs,
     ):
         """
-        Spin the base in place `angle` degrees, at the given angular `velocity`,
+        Spin the base in place ``angle`` degrees, at the given angular ``velocity``,
         expressed in degrees per second.
-        When `velocity` is 0, the base will stop.
+        When ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
         Args:
@@ -75,10 +75,10 @@ async def set_power(
         **kwargs,
     ):
         """Set the linear and angular velocity of the Base
-        When `linear` is 0, the the base will spin.
-        When `angular` is 0, the the base will move in a straight line.
-        When both `linear` and `angular` are 0, the base will stop.
-        When `linear` and `angular` are both nonzero, the base will move in an arc,
+        When ``linear`` is 0, the the base will spin.
+        When ``angular`` is 0, the the base will move in a straight line.
+        When both ``linear`` and ``angular`` are 0, the base will stop.
+        When ``linear`` and ``angular`` are both nonzero, the base will move in an arc,
         with a tighter radius if angular power is greater than linear power.
 
         Args:

src/viam/components/board/board.py

@@ -16,8 +16,8 @@ class Board(ComponentBase):
     components such as analog readers, and digital interrupts.
 
     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.
+    board implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
     """
 
     @dataclass
@@ -70,14 +70,14 @@ async def tick(self, high: bool, nanos: int):
                 high (bool): If the signal of the interrupt is high.
                 nanos (int): Nanoseconds from an arbitrary point in time,
                     but always increasing and always needs to be accurate.
-                    Using `time.time_ns()` would be acceptable.
+                    Using ``time.time_ns()`` would be acceptable.
             """
             ...
 
         @abc.abstractmethod
         async def add_callback(self, queue: Queue):
             """
-            Add a callback to be sent the low/high value on `tick()`.
+            Add a callback to be sent the low/high value on ``tick()``.
 
             Args:
                 queue (Queue): The receiving queue.
@@ -88,7 +88,7 @@ async def add_callback(self, queue: Queue):
         async def add_post_processor(self, processor: PostProcessor):
             """
             Add a post processor that should be used to modify what
-            is returned by `self.value()`
+            is returned by ``self.value()``
 
             Args:
                 processor (PostProcessor): The post processor to add.
@@ -133,7 +133,7 @@ async def get_pwm(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Opti
         @abc.abstractmethod
         async def set_pwm(self, duty_cycle: float, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
             """
-            Set the pin to the given `duty_cycle`.
+            Set the pin to the given ``duty_cycle``.
 
             Args:
                 duty_cycle (float): The duty cycle.
@@ -160,8 +160,8 @@ async def set_pwm_frequency(
             **kwargs,
         ):
             """
-            Set the pin to the given PWM `frequency` (in Hz).
-            When `frequency` is 0, it will use the board's default PWM frequency.
+            Set the pin to the given PWM ``frequency`` (in Hz).
+            When ``frequency`` is 0, it will use the board's default PWM frequency.
 
             Args:
                 frequency (int): The frequency, in Hz.
@@ -171,7 +171,7 @@ async def set_pwm_frequency(
     @abc.abstractmethod
     async def analog_reader_by_name(self, name: str) -> AnalogReader:
         """
-        Get an AnalogReader by `name`.
+        Get an AnalogReader by ``name``.
 
         Args:
             name (str): Name of the analog reader to be retrieved.
@@ -184,7 +184,7 @@ async def analog_reader_by_name(self, name: str) -> AnalogReader:
     @abc.abstractmethod
     async def digital_interrupt_by_name(self, name: str) -> DigitalInterrupt:
         """
-        Get a DigitalInterrupt by `name`.
+        Get a DigitalInterrupt by ``name``.
 
         Args:
             name (str): Name of the digital interrupt.
@@ -197,7 +197,7 @@ async def digital_interrupt_by_name(self, name: str) -> DigitalInterrupt:
     @abc.abstractmethod
     async def gpio_pin_by_name(self, name: str) -> GPIOPin:
         """
-        Get a GPIO Pin by `name`.
+        Get a GPIO Pin by ``name``.
 
         Args:
             name (str): Name of the GPIO pin.

src/viam/components/camera/camera.py

@@ -14,15 +14,15 @@ class Camera(ComponentBase):
     Camera represents any physical hardware that can capture frames.
 
     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.
+    camera implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
     """
 
     class Properties(NamedTuple):
         """The camera's supported features and settings"""
 
         supports_pcd: bool
-        """Whether the camera has a valid implementation of `get_point_cloud`"""
+        """Whether the camera has a valid implementation of ``get_point_cloud``"""
 
         intrinsic_parameters: IntrinsicParameters
         """The properties of the camera"""

src/viam/components/component_base.py

@@ -43,7 +43,7 @@ def get_resource_name(cls, name: str) -> ResourceName:
 
     @classmethod
     def from_robot(cls, robot: "RobotClient", name: str) -> Self:
-        """Get the component named `name` from the provided robot.
+        """Get the component named ``name`` from the provided robot.
 
         Args:
             robot (RobotClient): The robot
@@ -56,10 +56,11 @@ def from_robot(cls, robot: "RobotClient", name: str) -> Self:
         return cast(cls, component)
 
     def get_operation(self, kwargs: Mapping[str, Any]) -> Operation:
-        """Get the `Operation` associated with the currently running function.
+        """Get the ``Operation`` associated with the currently running function.
 
-        When writing custom components, you should get the `Operation` by calling this function and check to see if it's cancelled.
-        If the `Operation` is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc.).
+        When writing custom components, you should get the ``Operation`` by calling this function and check to see if it's cancelled.
+        If the ``Operation`` is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc.
+        ).
 
         Args:
             kwargs (Mapping[str, Any]): The kwargs object containing the operation

src/viam/components/gantry/gantry.py

@@ -12,8 +12,8 @@ class Gantry(ComponentBase):
     Gantry represents a physical Gantry and can be used for controlling gantries of N axes.
 
     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.
+    gantry implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
     """
 
     @abc.abstractmethod
@@ -43,7 +43,7 @@ async def move_to_position(
             positions (List[float]): List of positions for the axes to move to,
                 in millimeters.
             world_state (Optional[WorldState]): Object describing
-                obstacles for the gantry to avoid on its way to `positions`.
+                obstacles for the gantry to avoid on its way to ``positions``.
         """
         ...
 

src/viam/components/generic/client.py

@@ -29,7 +29,7 @@ async def do_command(self, command: Dict[str, Any], *, timeout: Optional[float]
 
 
 async def do_command(channel: Channel, name: str, command: Dict[str, Any], *, timeout: Optional[float] = None) -> Dict[str, Any]:
-    """Convenience method to allow component clients to execute `do_command` functions
+    """Convenience method to allow component clients to execute ``do_command`` functions
 
     Args:
         channel (Channel): A gRPC channel

src/viam/components/generic/generic.py

@@ -6,54 +6,51 @@ class Generic(ComponentBase):
     Generic component, which represents any type of component that can executes arbitrary commands
 
     This acts as an abstract base class for any drivers representing generic components.
-    This cannot be used on its own. If the `__init__()` function is overridden, it must call the `super().__init__()` function.
-
-    To create a Generic component (an arbitrary component that can process commands), this `Generic` component should be subclassed
-    and the `do_command` function implemented.
-
-    Example:
-
-    ```python
-    class ComplexComponent(Generic):
-
-        async def do_command(self, command: Dict[str, Any]) -> Dict[str, Any]:
-            result = {key: False for key in command.keys()}
-            for (name, args) in command.items():
-                if name == 'on':
-                    self.on(*args)
-                    result[name] = True
-                if name == 'set_frequency':
-                    self.set_frequency(*args)
-                    result[name] = True
-                if name == 'get_frequency':
-                    result[name] = self.frequency
-                if name == 'complex_command':
-                    self.complex_command(*args)
-                    result[name] = True
-            return result
-
-        def set_frequency(self, frequency: int):
-            self.frequency = frequency
-
-        def on(self, frequency: int, duration: int):
-            self.frequency = frequency
-            self.power = 1
-            task = threading.Timer(duration, self.off)
-            task.start()
-
-        def off(self):
-            self.power = 0
-
-        def complex_command(self, arg1, arg2, arg3):
-            ...
-    ```
-
-    To execute commands, simply call the `do_command` function with the appropriate parameters
-
-    ```python
-    await component.do_command({'on': [300, 10]})
-    component.power  # 1
-    await asyncio.sleep(10)
-    component.power  # 0
-    ```
+    This cannot be used on its own. If the ``__init__()`` function is overridden, it must call the ``super().__init__()`` function.
+
+    To create a Generic component (an arbitrary component that can process commands), this ``Generic`` component should be subclassed
+    and the ``do_command`` function implemented.
+
+    Example::
+
+        class ComplexComponent(Generic):
+
+            async def do_command(self, command: Dict[str, Any]) -> Dict[str, Any]:
+                result = {key: False for key in command.keys()}
+                for (name, args) in command.items():
+                    if name == 'on':
+                        self.on(*args)
+                        result[name] = True
+                    if name == 'set_frequency':
+                        self.set_frequency(*args)
+                        result[name] = True
+                    if name == 'get_frequency':
+                        result[name] = self.frequency
+                    if name == 'complex_command':
+                        self.complex_command(*args)
+                        result[name] = True
+                return result
+
+            def set_frequency(self, frequency: int):
+                self.frequency = frequency
+
+            def on(self, frequency: int, duration: int):
+                self.frequency = frequency
+                self.power = 1
+                task = threading.Timer(duration, self.off)
+                task.start()
+
+            def off(self):
+                self.power = 0
+
+            def complex_command(self, arg1, arg2, arg3):
+                ...
+
+    To execute commands, simply call the ``do_command`` function with the appropriate parameters.
+    ::
+
+        await component.do_command({'on': [300, 10]})
+        component.power  # 1
+        await asyncio.sleep(10)
+        component.power  # 0
     """

src/viam/components/generic/service.py

@@ -33,6 +33,6 @@ async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -
             timeout = stream.deadline.time_remaining() if stream.deadline else None
             result = await component.do_command(struct_to_dict(request.command), timeout=timeout)
         except NotImplementedError:
-            raise GRPCError(Status.UNIMPLEMENTED, f"`DO` command is unimplemented for component named: {name}")
+            raise GRPCError(Status.UNIMPLEMENTED, f"``DO`` command is unimplemented for component named: {name}")
         response = DoCommandResponse(result=dict_to_struct(result))
         await stream.send_message(response)