Fix docstring formatting for sphinx-autoapi compatibility

chipflow/platform/io/annotate.py

@@ -97,14 +97,21 @@ def annotations(self, origin , /):  # type: ignore
 
 
 def submodule_metadata(fragment: Fragment, component_name: str, recursive=False) -> Generator[Tuple[wiring.Component, str| tuple, dict]]:
-    """
-    Generator that finds `component_name` in `fragment` and
-    then yields the ``wiring.Component``s of that component's submodule, along with their names and metadata
+    """Generator that finds ``component_name`` in ``fragment`` and yields metadata.
+
+    Yields the ``wiring.Component`` instances of that component's submodule, along
+    with their names and metadata.
+
+    Can only be run once for a given component (or its children).
 
-    Can only be run once for a given component (or its children)
+    Args:
+        fragment: The fragment to search in.
+        component_name: The name of the component to find.
+        recursive: If True, name is a tuple of the hierarchy of names. Otherwise,
+            name is the string name of the first level component.
 
-    If recursive = True, then name is a tuple of the heirarchy of names
-    otherwise, name is the string name of the first level component
+    Yields:
+        Tuple of (component, name, metadata) for each submodule.
     """
 
     subfrag = fragment.find_subfragment(component_name)

chipflow/platform/io/iosignature.py

@@ -50,20 +50,22 @@ class IOTripPoint(StrEnum):
 
 
 class IOModelOptions(TypedDict):
-    """
-    Options for an IO pad/pin.
+    """Options for an IO pad/pin.
 
     Attributes:
-        invert: Polarity inversion. If the value is a simple :class:`bool`, it specifies inversion for
-            the entire port. If the value is an iterable of :class:`bool`, the iterable must have the
-            same length as the width of ``io``, and the inversion is specified for individual wires.
-        individual_oe: controls whether each output wire is associated with an individual Output Enable bit
-            or if a single OE bit will be used for entire port. The default value is False (indicating that a
-            single OE bit controls the entire port).
-        power_domain: The name of the I/O power domain. NB there is only one of these, so IO with
-            multiple power domains must be split up.
-        clock_domain: the name of the I/O's clock domain (see ``amaranth.hdl.ClockDomain``). NB there
-            is only one of these, so IO with multiple clocks must be split up.
+        invert: Polarity inversion. If the value is a simple ``bool``, it specifies
+            inversion for the entire port. If the value is an iterable of ``bool``,
+            the iterable must have the same length as the width of ``io``, and the
+            inversion is specified for individual wires.
+        individual_oe: Controls whether each output wire is associated with an
+            individual Output Enable bit or if a single OE bit will be used for
+            entire port. The default value is False (indicating that a single OE
+            bit controls the entire port).
+        power_domain: The name of the I/O power domain. NB there is only one of
+            these, so IO with multiple power domains must be split up.
+        clock_domain: The name of the I/O's clock domain (see
+            ``amaranth.hdl.ClockDomain``). NB there is only one of these, so IO
+            with multiple clocks must be split up.
         buffer_in: Should the IO pad have an input buffer?
         buffer_out: Should the IO pad have an output buffer?
         sky130_drive_mode: Drive mode for output buffer on sky130.

chipflow/platform/io/signatures.py

@@ -28,6 +28,13 @@
 DRIVER_MODEL_SCHEMA = str(_chipflow_schema_uri("driver-model", 0))
 
 class SimInterface(TypedDict):
+    """Simulation interface metadata for ChipFlow components.
+
+    Attributes:
+        uid: Unique identifier for the interface.
+        parameters: List of (name, value) tuples for interface parameters.
+    """
+
     uid: str
     parameters: List[Tuple[str, Any]]
 
@@ -78,7 +85,15 @@ def __init__(self, *, filename: Path, offset=0):
         self.offset = offset
 
 _T_DataClass = TypeVar('_T_DataClass', bound=DataclassProtocol)
+
+
 class Data(TypedDict, Generic[_T_DataClass]):
+    """Container for data associated with a ChipFlow component.
+
+    Attributes:
+        data: The dataclass instance containing component data.
+    """
+
     data: _T_DataClass
 
 

chipflow/platform/silicon.py

@@ -208,10 +208,14 @@ def __repr__(self):
 
 
 class Sky130Port(SiliconPlatformPort):
-    """
-    Specialisation of `SiliconPlatformPort` for the `Skywater sky130_fd_io__gpiov2 IO cell <https://skywater-pdk.readthedocs.io/en/main/contents/libraries/sky130_fd_io/docs/user_guide.html>`_
+    """Specialisation of ``SiliconPlatformPort`` for the Skywater sky130_fd_io__gpiov2 IO cell.
+
+    See the `Skywater PDK documentation
+    <https://skywater-pdk.readthedocs.io/en/main/contents/libraries/sky130_fd_io/docs/user_guide.html>`_
+    for more details.
 
-    Includes wires and configuration for `Drive Modes <IODriveMode>`, `Input buffer trip point <IOTripPoint>`and buffer control
+    Includes wires and configuration for drive modes (see ``Sky130DriveMode``),
+    input buffer trip point (see ``IOTripPoint``), and buffer control.
     """
 
     _DriveMode_map = {