Redefine

Author: Tom-Willemsen

doc/conf.py

@@ -95,4 +95,5 @@
     "lmfit": ("https://lmfit.github.io/lmfit-py/", None),
     "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest/", None),
     "ibex_user_manual": ("https://isiscomputinggroup.github.io/ibex_user_manual/", None),
+    "genie_python": ("https://isiscomputinggroup.github.io/genie/", None),
 }

doc/plan_stubs/external_code.md

@@ -1,6 +1,4 @@
-# `call_sync` (calling external code)
-
-API reference: [`call_sync`](ibex_bluesky_core.plan_stubs.call_sync)
+# Calling external code ({py:obj}`~ibex_bluesky_core.plan_stubs.call_sync`)
 
 All interaction with the "outside world" should be via bluesky messages, and **not** directly called from
 within a plan. For example, the following is **bad**:
@@ -16,18 +14,18 @@ def bad_plan():
 ```
 
 ```{danger}
-External I/O - including most `genie_python` or `inst` functions -  should never be done directly in a plan,
+External I/O - including most {py:obj}`genie_python <genie>` or `inst` functions -  should never be done directly in a plan,
 as it will break:
 - Rewindability (for example, the ability to interrupt a scan and then later seamlessly continue it)
-- Simulation (the `cset` above would be executed during a simulation)
+- Simulation (the {py:obj}`~genie.cset` above would be executed during a simulation)
 - Error handling (including ctrl-c handling)
 - Ability to emit documents
 - Ability to use bluesky signals
 - ...
 ```
 
 In the above case, a good plan, which uses bluesky messages in a better way using 
-a bluesky-native `Block` object, would be:
+a [bluesky-native block object](/devices/blocks), would be:
 
 ```python
 import bluesky.plan_stubs as bps
@@ -44,7 +42,7 @@ def good_plan():
 ```
 
 However, if the functionality you want to use is not yet natively available in bluesky, a fallback option
-for synchronous functions is available using the [`call_sync`](ibex_bluesky_core.plan_stubs.call_sync) plan stub:
+for synchronous functions is available using the {py:obj}`ibex_bluesky_core.plan_stubs.call_sync` plan stub:
 
 ```python
 import bluesky.plan_stubs as bps
@@ -61,6 +59,6 @@ def good_plan():
 ```
 
 It is strongly recommended that any functions run in this way are "fast" (i.e. less than a few seconds).
-In particular, avoid doing arbitrarily-long waits - for example, waiting for detector data
-or sample environment. For these long-running tasks, seek to implement at least the long-running parts using 
+In particular, avoid doing arbitrarily long waits - for example, waiting for detector data
+or sample environment. For these long running tasks, seek to implement at least the long-running parts using 
 native bluesky mechanisms.

doc/plan_stubs/matplotlib_helpers.md

@@ -1,23 +1,23 @@
-# [`call_qt_aware`](ibex_bluesky_core.plan_stubs.call_qt_aware) (matplotlib helpers)
+# Matplotlib helpers ({py:obj}`~ibex_bluesky_core.plan_stubs.call_qt_aware`)
 
-When attempting to use `matplotlib` UI functions directly in a plan, and running `matplotlib` using a `Qt`
+When attempting to use {py:obj}`matplotlib` UI functions directly in a plan, and running {py:obj}`matplotlib` using a Qt
 backend (e.g. in a standalone shell outside IBEX), you may see a hang or an error of the form:
 
 ```
 UserWarning: Starting a Matplotlib GUI outside of the main thread will likely fail.
   fig, ax = plt.subplots()
 ```
 
-This is because the `RunEngine` runs plans in a worker thread, not in the main thread, which then requires special
+This is because the bluesky run engine runs plans in a worker thread, not in the main thread, which then requires special
 handling when calling functions that will update a UI.
 
-The [`call_qt_aware`](ibex_bluesky_core.plan_stubs.call_qt_aware) plan stub can call `matplotlib` functions in a
+The {py:obj}`~ibex_bluesky_core.plan_stubs.call_qt_aware` plan stub can call {py:obj}`matplotlib` functions in a
 Qt-aware context, which allows them to be run directly from a plan. It allows the same arguments and 
 keyword-arguments as the underlying matplotlib function it is passed.
 
 ```{note}
-Callbacks such as `LivePlot` and `LiveFitPlot` already route UI calls to the appropriate UI thread by default. 
-The following plan stubs are only necessary if you need to call functions which will create or update a matplotlib
+Callbacks such as {py:obj}`~ibex_bluesky_core.callbacks.LivePlot` and {py:obj}`~bluesky.callbacks.mpl_plotting.LiveFitPlot` already route UI calls to the appropriate UI thread by default. 
+The {py:obj}`~ibex_bluesky_core.plan_stubs.call_qt_aware` plan stub is only necessary if you need to call functions which will create or update a matplotlib
 plot from a plan directly - for example to create or close a set of axes before passing them to callbacks.
 ```
 

doc/plan_stubs/polling.md

@@ -1,6 +1,9 @@
 # Continuous polling
 
-[`polling_plan`](ibex_bluesky_core.plans.polling_plan) - is used for moving a motor and dropping updates from a "readable" if no motor updates are provided. An example of this is a laser reading which updates much more quickly than a motor might register it's moved, so the laser readings are not really useful information.
+{py:obj}`ibex_bluesky_core.plans.polling_plan` can be used to perform a software continuous scan - setting off a motor
+move, and then monitoring both the motor position and a readable, zipping them together into a single dataset suitable
+for our usual plotting and fitting callbacks.
 
-This in itself doesn't start a bluesky "run" so you will need to use a `run_decorator` on any outer plan which calls this plan stub. 
+Updates from the readable may be dropped if they occur at a higher rate than updates from the motor position.
 
+{py:obj}`ibex_bluesky_core.plans.polling_plan` does not start a bluesky run, so you will need to use a {py:obj}`~bluesky.preprocessors.run_decorator` on an outer plan which calls this plan stub. This is so that _multiple_ continuous moves can be done as part of the same bluesky run.

doc/plan_stubs/redefining.md

@@ -3,7 +3,7 @@
 The plan stubs in this module implement 'redefinition' of a parameter, where supported. That is, no physical movement
 occurs, but the reported position changes to the given position.
 
-## `redefine_motor`
+## {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor`
 
 The {py:obj}`ibex_bluesky_core.plan_stubs.redefine_motor` plan stub can be used to redefine the current
 position of a motor (for example a {py:obj}`ibex_bluesky_core.devices.block.BlockMot`) to a new value.
@@ -28,16 +28,16 @@ def my_plan():
     yield from redefine_motor(motor, 0.)
 ```
 
-By default, the {py:obj}`redefine_motor <ibex_bluesky_core.plan_stubs.redefine_motor>`
+By default, the {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor`
 plan stub sleeps for 1 second after redefining the motor. This avoids race conditions, where a motor is moved too soon
 after being redefined to a new position, and the redefined position has not yet been read back from the controller.
 This behaviour can be controlled with the `sleep` keyword argument to
-{py:obj}`redefine_motor <ibex_bluesky_core.plan_stubs.redefine_motor>`.
+{py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor`.
 
-## `redefine_refl_parameter`
+## {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_refl_parameter`
 
 The {py:obj}`ibex_bluesky_core.plan_stubs.redefine_refl_parameter` plan stub can be used to redefine the current
-position of a {py:obj}`ibex_bluesky_core.devices.reflectometry.ReflParameter` to a new value. Note that some reflectometry parameters ie. `Theta` cannot be redefined, so these must be constructed with `has_redefine=False`. This plan stub will handle this case and raise an error if a user tries to redefine it. 
+position of a {py:obj}`~ibex_bluesky_core.devices.reflectometry.ReflParameter` to a new value. Note that some reflectometry parameters (e.g. `Theta`) cannot be redefined, so these must be constructed with `has_redefine=False`. {py:obj}`ibex_bluesky_core.plan_stubs.redefine_refl_parameter` will raise an error if a user tries to redefine a parameter that was created with `has_redefine=False`. 
 
-This plan stub has an identical API to that of the {py:obj}`ibex_bluesky_core.plan_stubs.redefine_motor` plan stub
+This plan stub has an identical API to that of the {py:obj}`~ibex_bluesky_core.plan_stubs.redefine_motor` plan stub
 described above, but operates on a reflectometry parameter rather than a motor.