From f6137ea41021c5c4cc7634cc41e38198f3d7af51 Mon Sep 17 00:00:00 2001 From: Jack Harper Date: Wed, 25 Sep 2024 15:55:39 +0100 Subject: [PATCH] fix weird dataclass args formatting, show base classes, add watch to sphinx running doc --- doc/_templates/custom-module-template.rst | 1 + doc/dev/set_up_dev_environment.md | 2 +- src/ibex_bluesky_core/devices/block.py | 12 ++++++++---- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/doc/_templates/custom-module-template.rst b/doc/_templates/custom-module-template.rst index 40febe8..f483c41 100644 --- a/doc/_templates/custom-module-template.rst +++ b/doc/_templates/custom-module-template.rst @@ -11,6 +11,7 @@ .. automodule:: {{ fullname }} :members: + :show-inheritance: {% block modules %} {% if modules %} diff --git a/doc/dev/set_up_dev_environment.md b/doc/dev/set_up_dev_environment.md index 23f5bb9..5a878bf 100644 --- a/doc/dev/set_up_dev_environment.md +++ b/doc/dev/set_up_dev_environment.md @@ -67,4 +67,4 @@ the type of block expected by `demo_plan` To build the sphinx documentation locally run `sphinx-build doc _build` from the root of the repo. The generated output will be in the _build directory. -If you want to preview changes live, you can run `sphinx-autobuild doc _build` from the root of the repo instead which will start a local, hot-reloadable web server. +If you want to preview changes live, you can run `sphinx-autobuild doc _build --watch src` from the root of the repo instead which will start a local, hot-reloadable web server. This should rebuild the documentation whenever you change anything in src, which in turn will rebuild the API reference pages. diff --git a/src/ibex_bluesky_core/devices/block.py b/src/ibex_bluesky_core/devices/block.py index d151da1..cf77639 100644 --- a/src/ibex_bluesky_core/devices/block.py +++ b/src/ibex_bluesky_core/devices/block.py @@ -40,10 +40,12 @@ class BlockWriteConfig(Generic[T]): """Configuration settings for writing to blocks. - use_completion_callback: Whether to wait for an EPICS completion callback while setting + use_completion_callback: + Whether to wait for an EPICS completion callback while setting this block. Defaults to true, which is appropriate for most blocks. - set_success_func: An arbitrary function which is called to decide whether the block has + set_success_func: + An arbitrary function which is called to decide whether the block has set successfully yet or not. The function takes (setpoint, actual) as arguments and should return true if the value has successfully set and is "ready", or False otherwise. @@ -60,13 +62,15 @@ def check(setpoint: T, actual: T) -> bool: Defaults to None, which means no check is applied. - set_timeout_s: A timeout, in seconds, on the value being set successfully. The timeout + set_timeout_s: + A timeout, in seconds, on the value being set successfully. The timeout applies to the EPICS completion callback (if enabled) and the set success function (if provided), and excludes any configured settle time. Defaults to None, which means no timeout. - settle_time_s: A wait time, in seconds, which is unconditionally applied just before the set + settle_time_s: + A wait time, in seconds, which is unconditionally applied just before the set status is marked as complete. Defaults to zero. """