Fix API reference docs

docs/conf.py

@@ -69,6 +69,9 @@
     ("py:class", "'id'"),
     ("py:class", "typing_extensions.Literal"),
 ]
+nitpick_ignore_regex = [
+    ("py:class", "fastcs.*.T"),
+]
 
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted into the main body of the autoclass directive

docs/reference/api.md

@@ -1,17 +1,24 @@
 # API
 
-```{eval-rst}
-.. automodule:: fastcs
+This is the internal API reference for fastcs. The key modules are summarised below.
+
+## Controllers
 
-    ``fastcs``
-    -----------------------------------
+```{eval-rst}
+.. automodule:: fastcs.controller
+    :members:
 ```
 
-This is the internal API reference for fastcs
+## Attributes
 
 ```{eval-rst}
-.. data:: fastcs.__version__
-    :type: str
+.. automodule:: fastcs.attributes
+    :members:
+```
+
+## Datatypes
 
-    Version number as calculated by https://github.com/pypa/setuptools_scm
+```{eval-rst}
+.. automodule:: fastcs.datatypes
+    :members:
 ```

src/fastcs/attributes.py

@@ -7,7 +7,7 @@
 
 
 class AttrMode(Enum):
-    """Access mode of an `Attribute`."""
+    """Access mode of an ``Attribute``."""
 
     READ = 1
     WRITE = 2
@@ -16,15 +16,15 @@ class AttrMode(Enum):
 
 @runtime_checkable
 class Sender(Protocol):
-    """Protocol for setting the value of an `Attribute`."""
+    """Protocol for setting the value of an ``Attribute``."""
 
     async def put(self, controller: Any, attr: AttrW, value: Any) -> None:
         pass
 
 
 @runtime_checkable
 class Updater(Protocol):
-    """Protocol for updating the cached readback value of an `Attribute`."""
+    """Protocol for updating the cached readback value of an ``Attribute``."""
 
     update_period: float
 
@@ -34,15 +34,15 @@ async def update(self, controller: Any, attr: AttrR) -> None:
 
 @runtime_checkable
 class Handler(Sender, Updater, Protocol):
-    """Protocol encapsulating both `Sender` and `Updater`."""
+    """Protocol encapsulating both ``Sender`` and ``Updater``."""
 
     pass
 
 
 class Attribute(Generic[T]):
     """Base FastCS attribute.
 
-    Instances of this class added to a `Controller` will be used by the backend.
+    Instances of this class added to a ``Controller`` will be used by the backend.
     """
 
     def __init__(
@@ -77,7 +77,7 @@ def group(self) -> str | None:
 
 
 class AttrR(Attribute[T]):
-    """A read-only `Attribute`."""
+    """A read-only ``Attribute``."""
 
     def __init__(
         self,
@@ -109,7 +109,7 @@ def updater(self) -> Updater | None:
 
 
 class AttrW(Attribute[T]):
-    """A write-only `Attribute`."""
+    """A write-only ``Attribute``."""
 
     def __init__(
         self,
@@ -148,7 +148,7 @@ def sender(self) -> Sender | None:
 
 
 class AttrRW(AttrW[T], AttrR[T]):
-    """A read-write `Attribute`."""
+    """A read-write ``Attribute``."""
 
     def __init__(
         self,

src/fastcs/controller.py

@@ -26,9 +26,9 @@ class Controller(BaseController):
     """Top-level controller for a device.
 
     This is the primary class for implementing device support in FastCS. Instances of
-    this class can be loaded into a backend to access its `Attribute`s. The backend can
-    then perform a specific function with the set of `Attributes`, such as generating a
-    UI or creating parameters for a control system.
+    this class can be loaded into a backend to access its ``Attribute``s. The backend
+    can then perform a specific function with the set of ``Attributes``, such as
+    generating a UI or creating parameters for a control system.
     """
 
     def __init__(self) -> None:
@@ -46,10 +46,10 @@ def get_sub_controllers(self) -> list[SubController]:
 
 
 class SubController(BaseController):
-    """A subordinate to a `Controller` for managing a subset of a device.
+    """A subordinate to a ``Controller`` for managing a subset of a device.
 
-    An instance of this class can be registered with a parent `Controller` to include it
-    as part of a larger device.
+    An instance of this class can be registered with a parent ``Controller`` to include
+    it as part of a larger device.
     """
 
     def __init__(self, path: str) -> None:

src/fastcs/datatypes.py

@@ -23,7 +23,7 @@ def dtype(self) -> type[T]:  # Using property due to lack of Generic ClassVars
 
 @dataclass(frozen=True)
 class Int(DataType[int]):
-    """`DataType` mapping to builtin `int`."""
+    """`DataType` mapping to builtin ``int``."""
 
     @property
     def dtype(self) -> type[int]:
@@ -32,7 +32,7 @@ def dtype(self) -> type[int]:
 
 @dataclass(frozen=True)
 class Float(DataType[float]):
-    """`DataType` mapping to builtin `float`."""
+    """`DataType` mapping to builtin ``float``."""
 
     prec: int = 2
 
@@ -43,7 +43,7 @@ def dtype(self) -> type[float]:
 
 @dataclass(frozen=True)
 class Bool(DataType[bool]):
-    """`DataType` mapping to builtin `bool`."""
+    """`DataType` mapping to builtin ``bool``."""
 
     znam: str = "OFF"
     onam: str = "ON"
@@ -55,7 +55,7 @@ def dtype(self) -> type[bool]:
 
 @dataclass(frozen=True)
 class String(DataType[str]):
-    """`DataType` mapping to builtin `str`."""
+    """`DataType` mapping to builtin ``str``."""
 
     @property
     def dtype(self) -> type[str]: