docs: Lots of improvements to the documentation.

Signed-off-by: Tim 'mithro' Ansell <tansell@google.com>

scripts/python-skywater-pdk/skywater_pdk/base.py

@@ -42,6 +42,15 @@ def parse_pathname(pathname):
         String containing any filename extracted.
         String containing the file extension
 
+    See Also
+    --------
+    skywater_pdk.base.parse_filename
+    skywater_pdk.base.Cell
+    skywater_pdk.base.Library
+
+    Examples
+    --------
+
     >>> parse_pathname('skywater-pdk/libraries/sky130_fd_sc_hd/v0.0.1/cells/a2111o')
     (Cell(name='a2111o', library=Library(node=LibraryNode.SKY130, source=LibrarySource('fd'), type=LibraryType.sc, name='hd', version=LibraryVersion(milestone=0, major=0, minor=1, commits=0, hash=''))), None)
 
@@ -160,6 +169,15 @@ def parse_filename(pathname) -> Tuple[LibraryOrCell, Optional[str], Optional[str
     ext : str, optional
         String containing the file extension
 
+    See Also
+    --------
+    skywater_pdk.base.parse_pathname
+    skywater_pdk.base.Cell
+    skywater_pdk.base.Library
+
+    Examples
+    --------
+
     >>> t = list(parse_filename('sky130_fd_io__top_ground_padonlyv2__tt_1p80V_3p30V_3p30V_25C.wrap.lib'))
     >>> t.pop(0)
     Cell(name='top_ground_padonlyv2', library=Library(node=LibraryNode.SKY130, source=LibrarySource('fd'), type=LibraryType.io, name='', version=None))
@@ -245,7 +263,17 @@ SEPERATOR = "__"
 @dataclass_json
 @dataclass(order=True, frozen=True)
 class LibraryVersion:
-    """
+    """Version number for a library.
+
+    See Also
+    --------
+    skywater_pdk.base.LibraryNode
+    skywater_pdk.base.LibrarySource
+    skywater_pdk.base.LibraryType
+    skywater_pdk.base.LibraryVersion
+
+    Examples
+    --------
 
     >>> v0 = LibraryVersion.parse("v0.0.0")
     >>> v0
@@ -314,6 +342,8 @@ class LibraryVersion:
 
 
 class LibraryNode(Enum):
+    """Process node for a library."""
+
     SKY130 = "SkyWater 130nm"
 
     @classmethod
@@ -371,6 +401,8 @@ LibrarySource.Known.append(OSU)
 
 
 class LibraryType(Enum):
+    """Type of library contents."""
+
     pr = "Primitives"
     sc = "Standard Cells"
     sp = "Build Space (Flash, SRAM, etc)"
@@ -397,7 +429,20 @@ class LibraryType(Enum):
 @dataclass_json
 @dataclass
 class Library:
-    """
+    """Library of cells.
+
+    See Also
+    --------
+    skywater_pdk.base.parse_pathname
+    skywater_pdk.base.parse_filename
+    skywater_pdk.base.Cell
+    skywater_pdk.base.LibraryNode
+    skywater_pdk.base.LibrarySource
+    skywater_pdk.base.LibraryType
+    skywater_pdk.base.LibraryVersion
+
+    Examples
+    --------
 
     >>> l = Library.parse("sky130_fd_sc_hd")
     >>> l
@@ -463,7 +508,17 @@ class Library:
 @dataclass_json
 @dataclass
 class Cell:
-    """
+    """Cell in a library.
+
+    See Also
+    --------
+    skywater_pdk.base.parse_pathname
+    skywater_pdk.base.parse_filename
+    skywater_pdk.base.Library
+
+    Examples
+    --------
+
     >>> c = Cell.parse("sky130_fd_sc_hd__abc")
     >>> c
     Cell(name='abc', library=Library(node=LibraryNode.SKY130, source=LibrarySource('fd'), type=LibraryType.sc, name='hd', version=None))

scripts/python-skywater-pdk/skywater_pdk/sizes.py

@@ -65,6 +65,15 @@ class InvalidSuffixError(ValueError):
 class CellSize(abc.ABC):
     """Drive strength variants of a given cell.
 
+    See Also
+    --------
+    skywater_pdk.base.Cell
+    skywater_pdk.sizes.CellSizeNumeric
+    skywater_pdk.sizes.CellSizeLowPower
+    skywater_pdk.sizes.CellSizeMinimum
+
+    Examples
+    --------
     >>> d1 = CellSize.from_suffix("_1")
     >>> d2 = CellSize.from_suffix("_lp")
     >>> d3 = CellSize.from_suffix("_m")
@@ -138,6 +147,16 @@ class CellSize(abc.ABC):
 @dataclass(frozen=True)
 class CellSizeNumeric(CellSize):
     """
+
+    See Also
+    --------
+    skywater_pdk.base.Cell
+    skywater_pdk.sizes.CellSize
+    skywater_pdk.sizes.CellSizeLowPower
+    skywater_pdk.sizes.CellSizeMinimum
+
+    Examples
+    --------
     >>> s1 = CellSizeNumeric.from_suffix("_1")
     >>> s2 = CellSizeNumeric.from_suffix("_2")
     >>> s3 = CellSizeNumeric.from_suffix("_3")
@@ -199,6 +218,16 @@ class CellSizeNumeric(CellSize):
 @dataclass(frozen=True)
 class CellSizeLowPower(CellSize):
     """
+
+    See Also
+    --------
+    skywater_pdk.base.Cell
+    skywater_pdk.sizes.CellSize
+    skywater_pdk.sizes.CellSizeNumeric
+    skywater_pdk.sizes.CellSizeMinimum
+
+    Examples
+    --------
     >>> lp = CellSizeLowPower.from_suffix("_lp")
     >>> lp2 = CellSizeLowPower.from_suffix("_lp2")
     >>> lp3 = CellSizeLowPower.from_suffix("_lp3")
@@ -270,6 +299,17 @@ class CellSizeLowPower(CellSize):
 
 class CellSizeMinimum(CellSize):
     """
+
+    See Also
+    --------
+    skywater_pdk.base.Cell
+    skywater_pdk.sizes.CellSize
+    skywater_pdk.sizes.CellSizeNumeric
+    skywater_pdk.sizes.CellSizeLowPower
+
+
+    Examples
+    --------
     >>> m = CellSizeMinimum.from_suffix("_m")
     >>> CellSizeMinimum.from_suffix("_m2")
     Traceback (most recent call last):

scripts/python-skywater-pdk/skywater_pdk/utils.py

@@ -19,6 +19,7 @@
 
 import dataclasses
 import dataclasses_json
+import functools
 import random
 import sys
 
@@ -64,6 +65,9 @@ def dataclass_json_passthru_sequence_config(*args, **kw):
 def comparable_to_none(cls):
     """
 
+    Examples
+    --------
+
     >>> @comparable_to_none
     ... @dataclass(order=True)
     ... class A:
@@ -124,11 +128,20 @@ def comparable_to_none(cls):
             s = super().__repr__()
             return s.replace('comparable_to_none.<locals>.ComparableToNoneVersion', cls.__name__)
 
+    for a in functools.WRAPPER_ASSIGNMENTS:
+        if not hasattr(cls, a):
+            continue
+        setattr(ComparableToNoneVersion, a, getattr(cls, a))
+
     return ComparableToNoneVersion
 
 
 def _is_optional_type(t):
     """
+
+    Examples
+    --------
+
     >>> _is_optional_type(Optional[int])
     True
     >>> _is_optional_type(Optional[Tuple])
@@ -141,6 +154,10 @@ def _is_optional_type(t):
 
 def _get_the_optional_type(t):
     """
+
+    Examples
+    --------
+
     >>> _get_the_optional_type(Optional[int])
     <class 'int'>
     >>> _get_the_optional_type(Optional[Tuple])
@@ -158,6 +175,10 @@ def _get_the_optional_type(t):
 
 def _get_type_name(ot):
     """
+
+    Examples
+    --------
+
     >>> _get_type_name(int)
     'int'
     >>> _get_type_name(Tuple)