corrections to documentation and code

Author: danielmaclaren

doc/plan_stubs/plan_wrappers.md

@@ -1,78 +1,86 @@
-# Plan Wrappers
+# Plan wrappers
 
-Plan wrappers that temporarily modify [DAE (Data Acquisition Electronics)](https://isiscomputinggroup.github.io/ibex_bluesky_core/devices/dae.html#dae-data-acquisition-electronics) settings during a plan, automatically restoring the original values afterwards. This ensures that your experiments don't permanently change instrument configuration.
+Plan wrappers that temporarily modify [DAE (Data Acquisition Electronics)](/devices/dae.md) settings during a plan, automatically restoring the original values afterwards. This ensures that your experiments don't permanently change instrument configuration.
 
 ## Available Wrappers
 
 ### DAE Table
 
-:py:obj:`dae_table_wrapper <ibex_bluesky_core.plan_stubs.dae_table_wrapper>`
+A function that wraps a plan to temporarily modify the DAE table.
+
+API reference: {py:obj}`dae_table_wrapper<ibex_bluesky_core.plan_stubs.with_dae_tables>`
 
 ```python
 RE(
-    _with_dae_tables(
+    with_dae_tables(
         bps.null(),
         dae=dae,
         new_settings=modified_settings
-        )
     )
+)
+```
+```python
+def plan():
+    yield from with_dae_tables(scan(...), dae=dae, new_settings=modified_settings)
 ```
 
-Where `modified_settings` is a dataset in the form :py:obj:`DaeSettingsData < ibex_bluesky_core.devices.dae.DaeSettingsData>`
+(where `modified_settings` is a dataset in the form {py:obj}`DaeSettingsData <ibex_bluesky_core.devices.dae.DaeSettingsData>`)
+
 
-A function that wraps a plan to temporarily modify the DAE table.
 
 ### Num Periods
-:py:obj:`num_periods_wrapper <ibex_bluesky_core.plan_stubs.num_periods_wrapper>`
+
+A function that wraps a plan to temporarily modify the number of periods.
+
+API reference: {py:obj}`num_periods_wrapper<ibex_bluesky_core.plan_stubs.with_num_periods>`
 
 ```python
 RE(
-    _with_num_periods(
+    with_num_periods(
         bps.null(),
         dae=dae,
         number_of_periods=1000 
-        )
     )
+)
+```
+```python
+def plan():
+    yield from with_num_periods(scan(...), dae=dae, number_of_periods=1000)
 ```
-A function that wraps a plan to temporarily modify the number of periods.
+
 
 ### Time Channels
-:py:obj:`time_channels_wrapper <ibex_bluesky_core.plan_stubs.time_channels_wrapper>`:
+A function that wraps a plan to temporarily modify the time channels boundaries.
+
+API reference: {py:obj}`time_channels_wrapper<ibex_bluesky_core.plan_stubs.with_time_channels>`
 
 ```python
 RE(
-    _with_time_channels(
+    with_time_channels(
         bps.null(),
         dae=dae,
         new_settings=modified_settings
-        )
     )
+)
 ```
-Where `modified_settings` is a dataset in the form :py:obj:`DaeTCBSettingsData < ibex_bluesky_core.devices.dae.DaeTCBSettingsData>`
-
-A function that wraps a plan to temporarily modify the time channels boundaries.
+```python
+def plan():
+    yield from with_time_channels(scan(...), dae=dae, new_settings=modified_settings)
+```
+(where `modified_settings` is a dataset in the form {py:obj}`DaeTCBSettingsData<ibex_bluesky_core.devices.dae.DaeTCBSettingsData>`)
 
 ## Usage
 
 To use these wrappers, the plan written by the user must be wrapped by the function within the RunEngine:
 
 ``` python
-
-from bluesky import RunEngine
-from ibex_bluesky_core.plan_stubs import _with_num_periods
+from ibex_bluesky_core.plan_stubs import with_num_periods
 from ibex_bluesky_core.devices.simpledae import SimpleDae
 
 dae = SimpleDae() # Give your DAE options here
-RE = RunEngine()
-
-RE(
-    _with_num_periods(
-        bps.null(), # Default plan to run
-        dae=dae,
-        number_of_periods=1000 # Temporary number of periods to run
-        )
-    )
 
+def plan():
+    yield from with_num_periods(scan(...), dae=dae, number_of_periods=1000)
 ```
 
 the plan with the modified DAE settings, restoring the original settings afterwards.

src/ibex_bluesky_core/plan_stubs/__init__.py

@@ -12,9 +12,9 @@
 from ophyd_async.epics.motor import Motor, UseSetMode
 
 from ibex_bluesky_core.devices.reflectometry import ReflParameter
-from ibex_bluesky_core.plan_stubs.dae_table_wrapper import _with_dae_tables
-from ibex_bluesky_core.plan_stubs.num_periods_wrapper import _with_num_periods
-from ibex_bluesky_core.plan_stubs.time_channels_wrapper import _with_time_channels
+from ibex_bluesky_core.plan_stubs._dae_table_wrapper import with_dae_tables
+from ibex_bluesky_core.plan_stubs._num_periods_wrapper import with_num_periods
+from ibex_bluesky_core.plan_stubs._time_channels_wrapper import with_time_channels
 from ibex_bluesky_core.utils import NamedReadableAndMovable
 
 logger = logging.getLogger(__name__)
@@ -28,9 +28,9 @@
 
 
 __all__ = [
-    "_with_dae_tables",
-    "_with_num_periods",
-    "_with_time_channels",
+    "with_dae_tables",
+    "with_num_periods",
+    "with_time_channels",
     "call_qt_aware",
     "call_sync",
     "polling_plan",

…sky_core/plan_stubs/dae_table_wrapper.py …ky_core/plan_stubs/_dae_table_wrapper.pysrc/ibex_bluesky_core/plan_stubs/dae_table_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_dae_table_wrapper.py src/ibex_bluesky_core/plan_stubs/dae_table_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_dae_table_wrapper.py

@@ -10,7 +10,7 @@
 from ibex_bluesky_core.devices.dae import Dae, DaeSettingsData
 
 
-def _with_dae_tables(
+def with_dae_tables(
     plan: Generator[Msg, None, None], dae: Dae, new_settings: DaeSettingsData
 ) -> Generator[Msg, None, None]:
     """Wrap a plan with temporary modification to DAE Settings.
@@ -35,7 +35,7 @@ def _inner() -> Generator[Msg, None, None]:
 
         yield from bps.mv(dae.dae_settings, new_settings)
 
-        yield from plan
+        return (yield from plan)
 
     def _cleanup() -> Generator[Msg, None, None]:
         yield from bps.mv(dae.dae_settings, original_dae_setting)

…y_core/plan_stubs/num_periods_wrapper.py …_core/plan_stubs/_num_periods_wrapper.pysrc/ibex_bluesky_core/plan_stubs/num_periods_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_num_periods_wrapper.py src/ibex_bluesky_core/plan_stubs/num_periods_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_num_periods_wrapper.py

@@ -10,7 +10,7 @@
 from ibex_bluesky_core.devices.dae import Dae
 
 
-def _with_num_periods(
+def with_num_periods(
     plan: Generator[Msg, None, None], dae: Dae, number_of_periods: int
 ) -> Generator[Msg, None, None]:
     """Wrap a plan with temporary modification to Periods Settings.
@@ -34,7 +34,7 @@ def _inner() -> Generator[Msg, None, None]:
 
         yield from bps.mv(dae.number_of_periods, number_of_periods)
 
-        yield from plan
+        return (yield from plan)
 
     def _cleanup() -> Generator[Msg, None, None]:
         yield from bps.mv(dae.number_of_periods, original_num_periods)

…core/plan_stubs/time_channels_wrapper.py …ore/plan_stubs/_time_channels_wrapper.pysrc/ibex_bluesky_core/plan_stubs/time_channels_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_time_channels_wrapper.py src/ibex_bluesky_core/plan_stubs/time_channels_wrapper.py renamed to src/ibex_bluesky_core/plan_stubs/_time_channels_wrapper.py

@@ -10,7 +10,7 @@
 from ibex_bluesky_core.devices.dae import Dae, DaeTCBSettingsData
 
 
-def _with_time_channels(
+def with_time_channels(
     plan: Generator[Msg, None, None], dae: Dae, new_tcb_settings: DaeTCBSettingsData
 ) -> Generator[Msg, None, None]:
     """Wrap a plan with temporary modification to Time Channel Settings.
@@ -35,7 +35,7 @@ def _inner() -> Generator[Msg, None, None]:
 
         yield from bps.mv(dae.tcb_settings, new_tcb_settings)
 
-        yield from plan
+        return (yield from plan)
 
     def _cleanup() -> Generator[Msg, None, None]:
         yield from bps.mv(dae.tcb_settings, original_time_channels)

tests/test_plan_stubs.py

@@ -26,9 +26,9 @@
 from ibex_bluesky_core.devices.reflectometry import ReflParameter
 from ibex_bluesky_core.plan_stubs import (
     CALL_QT_AWARE_MSG_KEY,
-    _with_dae_tables,
-    _with_num_periods,
-    _with_time_channels,
+    with_dae_tables,
+    with_num_periods,
+    with_time_channels,
     call_qt_aware,
     call_sync,
     prompt_user_for_choice,
@@ -202,9 +202,9 @@ def test_num_periods_wrapper(dae: Dae, RE: RunEngine):
 
     set_mock_value(dae.number_of_periods.signal, original_settings)
 
-    with patch("ibex_bluesky_core.plan_stubs.num_periods_wrapper.ensure_connected"):
+    with patch("ibex_bluesky_core.plan_stubs._num_periods_wrapper.ensure_connected"):
         RE(
-            _with_num_periods(
+            with_num_periods(
                 bps.null(),
                 dae=dae,
                 number_of_periods=80,
@@ -480,8 +480,8 @@ def test_time_channels_wrapper(dae: Dae, RE: RunEngine):
         dae.tcb_settings._raw_tcb_settings, compress_and_hex(original_tcb_settings).decode()
     )
 
-    with patch("ibex_bluesky_core.plan_stubs.time_channels_wrapper.ensure_connected"):
-        RE(_with_time_channels(bps.null(), dae=dae, new_tcb_settings=modified_settings))
+    with patch("ibex_bluesky_core.plan_stubs._time_channels_wrapper.ensure_connected"):
+        RE(with_time_channels(bps.null(), dae=dae, new_tcb_settings=modified_settings))
 
     mock_set_calls = get_mock_put(dae.tcb_settings._raw_tcb_settings).call_args_list
 
@@ -556,8 +556,8 @@ def test_dae_table_wrapper(dae: Dae, RE: RunEngine):
 
     set_mock_value(dae.dae_settings._raw_dae_settings, original_settings)
 
-    with patch("ibex_bluesky_core.plan_stubs.dae_table_wrapper.ensure_connected"):
-        RE(_with_dae_tables(bps.null(), dae=dae, new_settings=modified_settings))
+    with patch("ibex_bluesky_core.plan_stubs._dae_table_wrapper.ensure_connected"):
+        RE(with_dae_tables(bps.null(), dae=dae, new_settings=modified_settings))
 
     mock_set_calls = get_mock_put(dae.dae_settings._raw_dae_settings).call_args_list