From f887045ccb3f1c336ab3b0d36f412a8117705ca3 Mon Sep 17 00:00:00 2001 From: Gary Yendell Date: Wed, 20 Mar 2024 16:50:24 +0000 Subject: [PATCH] Fix API reference docs --- docs/conf.py | 3 +++ docs/reference/api.md | 23 +++++++++++++++-------- src/fastcs/attributes.py | 16 ++++++++-------- src/fastcs/controller.py | 12 ++++++------ src/fastcs/datatypes.py | 8 ++++---- 5 files changed, 36 insertions(+), 26 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ccca0a25..44a2a1de 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/reference/api.md b/docs/reference/api.md index 4d73688b..e799d1b4 100644 --- a/docs/reference/api.md +++ b/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: ``` diff --git a/src/fastcs/attributes.py b/src/fastcs/attributes.py index eac21770..3d182f65 100644 --- a/src/fastcs/attributes.py +++ b/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,7 +16,7 @@ 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 @@ -24,7 +24,7 @@ async def put(self, controller: Any, attr: AttrW, value: Any) -> None: @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,7 +34,7 @@ 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 @@ -42,7 +42,7 @@ class Handler(Sender, Updater, Protocol): 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, diff --git a/src/fastcs/controller.py b/src/fastcs/controller.py index 783bcbaf..1464c06d 100755 --- a/src/fastcs/controller.py +++ b/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: diff --git a/src/fastcs/datatypes.py b/src/fastcs/datatypes.py index f085794e..ccb361d0 100644 --- a/src/fastcs/datatypes.py +++ b/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]: