plans

Author: Tom-Willemsen

doc/plans/plans.md

@@ -1,44 +1,48 @@
 # General Plans 
 
-`ibex_bluesky_core` provides a number of plans that can be run by the RunEngine directly. These are mostly thin wrappers around the generic [bluesky plans](https://blueskyproject.io/bluesky/main/plans.html)
+The {py:obj}`ibex_bluesky_core.plans` module provides a number of plans that can be run by the RunEngine directly. These are mostly wrappers around the generic {external+bluesky:doc}`bluesky plans <plans>`.
 
-All of these plans can be used directly by the RunEngine (`RE()`) or within a wrapper of your own that yields from them (`yield from`)
+All of these plans can be used directly by the RunEngine (`RE()`), or within a wrapper of your own that `yields from` these plans.
 
 So you can do this: 
 
 ```python
+from ibex_bluesky_core.plans.reflectometry import refl_scan
+from ibex_bluesky_core.fitting import Gaussian
+
+
 result = RE(refl_scan("S1VG", 1, 10, 21, model=Gaussian().fit(), frames=500, det=100, mon=3, pixel_range=6, periods=True, save_run=False))
 ```
 
 or this: 
 
 ```python
 from ibex_bluesky_core.plans.reflectometry import refl_scan
+from ibex_bluesky_core.fitting import Gaussian
+
+
 def my_plan():
     ...  # Some stuff before scan
-    icc = (yield from refl_scan("S1VG", 1, 10, 21, model=Gaussian().fit(), frames=500, det=100, mon=3, pixel_range=6, periods=True, save_run=False))
+    icc = yield from refl_scan("S1VG", 1, 10, 21, model=Gaussian().fit(), frames=500, det=100, mon=3, pixel_range=6, periods=True, save_run=False)
     ...  # Some stuff after scan
 ```
 
-## Return values
-
-The scanning plans documented on this page will return an [`ISISCallbacks`](ibex_bluesky_core.callbacks.ISISCallbacks) instance, which gives results of fits, centre of masses etc. - for example in your own plan if you wanted to print the fit result and the centre of mass:
+The scanning plans documented on this page will return a {py:obj}`~ibex_bluesky_core.callbacks.ISISCallbacks` instance, which can be used to access results of fits, centre of mass, and other callbacks:
 
 ```python
 from ibex_bluesky_core.plans import motor_scan
 def my_plan():
     icc = (yield from motor_scan("MyBlock1", 1, 10, 21, model=Gaussian().fit(), frames=500, det=100, mon=3, pixel_range=6, periods=True, save_run=False))
     print(icc.live_fit.result.fit_report())
-    print(f"COM: {icc.peak_stats['com']}")
+    print(f"COM: {icc.com.result}")
 ```
 
-## Lower-level plans
+## Plans taking _devices_ as arguments
 
 These take "devices" so you can pass your own DAE object and a movable/readable but use a standard set of callbacks for plotting, fitting and log file writing. These are designed to allow flexibility such as more in-depth DAE customisation, block configuration ie write tolerances, settle times. 
 
-[`scan`](ibex_bluesky_core.plans.scan) - this is for a absolute/relative scan.
-
-[`adaptive_scan`](ibex_bluesky_core.plans.adaptive_scan) - this is for an adaptive/relative-adaptive scan.
+- {py:obj}`ibex_bluesky_core.plans.scan` - this is an absolute/relative scan.
+- {py:obj}`ibex_bluesky_core.plans.adaptive_scan` - this is for an adaptive/relative-adaptive scan.
 
 An example of using one of these could be: 
 
@@ -56,18 +60,18 @@ def my_plan():
 
 ```
 
-which would be used on the console like so: `RE(my_plan)`
+which would be used on the console as: `RE(my_plan())`
 
-## Higher-level wrapper plans 
-Alternatively, we provide some very thin wrappers which construct the devices for you - these are:
+## Plans taking _names_ as arguments
 
-[`motor_scan`](ibex_bluesky_core.plans.motor_scan)
+Alternatively, we provide some wrappers that construct the devices for you - these are:
 
-[`motor_adaptive_scan`](ibex_bluesky_core.plans.motor_scan)
+- {py:obj}`ibex_bluesky_core.plans.motor_scan`
+- {py:obj}`ibex_bluesky_core.plans.motor_adaptive_scan`
 
-which wrap the above respectively. These take _names_ of blocks, rather than devices themselves, and construct a DAE and block device for you, using the global moving flag to determine if a motor has finished moving (in the same way as a `waitfor_move()`). This might be useful if you have a fairly standard DAE setup and just want to scan a block pointing at a motor such as a Sample Changer axis, but is not as flexible or performant as the lower-level plans.
+These plans take the _names_ of blocks as arguments, rather than devices, and construct a DAE and block device for you, using the global moving flag to determine if a motor has finished moving (in the same way as a `waitfor_move()`). This might be useful if you have a fairly standard DAE setup and want to scan a block pointing at a motor such as a Sample Changer axis, but is not as flexible or performant as the lower-level plans.
 
-for example if you just wanted to scan over a motor, wait for 400 frames, and perform a linear fit, you can just write this in the console: 
+For example, to scan over a motor, wait for 400 frames, and perform a linear fit, you can write this in the console: 
 
 ```python
 >>> from ibex_bluesky_core.plans import motor_scan

doc/plans/reflectometry/autoalign.md

@@ -1,10 +1,8 @@
 # Auto-alignment
 
-For reflectometers, we provide a few generic plans which can be used to align beamlines.
+For reflectometers, we provide a few generic plans which can be used as helpers for automated beamline alignment.
 
-## Full-Auto Alignment Plan
-
-The {py:obj}`ibex_bluesky_core.plans.reflectometry.optimise_axis_against_intensity` plan is designed to scan over a movable against beam intensity, and given which fitting parameter is chosen to be optimised and the fitting method, it will aim to find an optimum value. See [`standard fits`](/callbacks/fitting/standard_fits.md) for the fitting parameters for each fitting model you can use. At this stage it will check if the value is 'sensible'- there are some default checks but the user is encouraged to provide their own checks. If found to be sensible, the motor will be moved to this value, otherwise it will optionally run a callback that can be provided, and then ask the user if they want to rescan or conttinue to move the movable.
+The {py:obj}`~ibex_bluesky_core.plans.reflectometry.optimise_axis_against_intensity` plan is designed to scan over a movable against beam intensity, and given which fitting parameter is chosen to be optimised and the fitting method, it will aim to find an optimum value. See [standard fits](/callbacks/fitting/standard_fits.md) for the fitting parameters for each fitting model you can use. At this stage it will check if the value is 'sensible' - there are some default checks, but the user is encouraged to provide their own checks. If found to be sensible, the motor will be moved to this value, otherwise it will optionally run a callback that can be provided, and then ask the user if they want to rescan or continue to move the movable.
 
 The idea for how we expect the main auto-alignment plan to be used is that at the top / instrument level, you will move all other movables to some position ready to align, yield from this plan and then re-zero the motor.
 The following is how you would do this for a reflectometry parameter as your movable: