Move beamline specific devies from dodal.devices.iXX to dodal.devices.beamlines.iXX (#1866)

* Move beamline specific devies from dodal.devices.iXX to dodal.devices.beamlines.iXX

* merge into main

* Fix tests from merge conflicts

* Fix test from merge conflict

* Update docs

Author: oliwenmandiamond

docs/how-to/create-device.md

@@ -27,7 +27,13 @@ For example, only use `XYStage` for two perpendicular motors (e.g. X and Y axes
 - Only a device that represents a group of motors with a physical relationship, should be defined in `motor`.
 - If your class define an `XYStage` but you need extra signals or behaviour, extend the `XYStage` class outside the `motor` module.
 
-**Only if no suitable class exists**, create a new device that connects to the required signals. During review, refactor to align with existing devices if needed, using inheritance or composition to deduplicate code.  
+**Only if no suitable class exists**, create a new device that connects to the required signals. During review, refactor to align with existing devices if needed, using inheritance or composition to deduplicate code.
+
+Devices that are generic and reusable across multiple beamlines should be defined under `dodal.devices`. For example, `dodal.devices.motors.XYStage` is generic enough that most beamlines can use it directly or inherit from it.
+
+Devices that are specific to a single beamline should be placed under `dodal.devices.beamlines.iXX`. For instance, a detector that is only used on that beamline and is too specialized to be reused elsewhere belongs here.
+
+If a beamline has multiple endstations and a device is shared between them, it should be defined under `dodal.devices.beamlines.iXX_shared`.
 
 Writing a device class
 ======================
@@ -36,7 +42,7 @@ To develop a new device, get an initial, working version of your code into the m
 
 - **Follow the [ophyd-async device implementation guide](https://blueskyproject.io/ophyd-async/main/tutorials/implementing-devices.html)** to structure your device code.
 - **Choose the right base class** by consulting the [base class guide](https://blueskyproject.io/ophyd-async/main/how-to/choose-right-baseclass.html), If your device needs to move, you'll need to extend the Movable protocol. For detailed guidance on when and how to do this, refer to the [movable device guide](https://blueskyproject.io/ophyd-async/main/explanations/when-to-extend-movable.html). 
-- **Add static metadata (if any) to the device class** using a [soft signal](https://blueskyproject.io/ophyd-async/main/_api/ophyd_async/ophyd_async.core.html#ophyd_async.core.soft_signal_rw) or existing device epics record. For example this could be a manufacturer or brand name of the device. Another example is crystal metadata in [i22 DCM](https://diamondlightsource.github.io/dodal/main/reference/generated/dodal.devices.i22.dcm.DCM.html#dodal.devices.i22.dcm.DCM) In some cases it might be beneficial to ask controls team to create an additional epics field containing metadata for such device. 
+- **Add static metadata (if any) to the device class** using a [soft signal](https://blueskyproject.io/ophyd-async/main/_api/ophyd_async/ophyd_async.core.html#ophyd_async.core.soft_signal_rw) or existing device epics record. For example this could be a manufacturer or brand name of the device. Another example is crystal metadata in [i22 DCM](https://diamondlightsource.github.io/dodal/main/reference/generated/dodal.devices.beamlines.i22.dcm.DCM.html#dodal.devices.beamlines.i22.dcm.DCM) In some cases it might be beneficial to ask controls team to create an additional epics field containing metadata for such device. 
 - **Write thorough unit tests** for all expected use cases. Reference the [ophyd-async device test guide](https://blueskyproject.io/ophyd-async/main/tutorials/implementing-devices.html) for best practices.
 - **Validate your device on the beamline** and keep notes of any issues for later fixes.
 - **Make use of type annotations** so that pyright will validate that you are passing around values that ophyd-async will accept.

src/dodal/beamlines/b07.py

@@ -1,7 +1,7 @@
 from dodal.beamlines.b07_shared import devices as b07_shared_devices
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.device_manager import DeviceManager
-from dodal.devices.b07 import Grating, LensMode, PsuMode
+from dodal.devices.beamlines.b07 import Grating, LensMode, PsuMode
 from dodal.devices.electron_analyser.base import EnergySource
 from dodal.devices.electron_analyser.specs import SpecsDetector
 from dodal.devices.pgm import PlaneGratingMonochromator

src/dodal/beamlines/b07_1.py

@@ -1,8 +1,8 @@
 from dodal.beamlines.b07_shared import devices as b07_shared_devices
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.device_manager import DeviceManager
-from dodal.devices.b07 import PsuMode
-from dodal.devices.b07_1 import (
+from dodal.devices.beamlines.b07 import PsuMode
+from dodal.devices.beamlines.b07_1 import (
     ChannelCutMonochromator,
     Grating,
     LensMode,

src/dodal/beamlines/b16.py

@@ -11,7 +11,7 @@
 )
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.common.visit import RemoteDirectoryServiceClient, StaticVisitPathProvider
-from dodal.devices.b16.detector import (
+from dodal.devices.beamlines.b16.detector import (
     software_triggered_tiff_area_detector,
 )
 from dodal.devices.motors import XYZStage

src/dodal/beamlines/b21.py

@@ -12,8 +12,8 @@
 )
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.common.beamlines.device_helpers import CAM_SUFFIX, HDF5_SUFFIX
+from dodal.devices.beamlines.i22.nxsas import NXSasMetadataHolder, NXSasOAV
 from dodal.devices.focusing_mirror import SimpleMirror
-from dodal.devices.i22.nxsas import NXSasMetadataHolder, NXSasOAV
 from dodal.devices.linkam3 import Linkam3
 from dodal.devices.motors import XYStage
 from dodal.devices.slits import Slits

src/dodal/beamlines/i02_1.py

@@ -9,9 +9,9 @@
     I02_1FilterThreeSelections,
     I02_1FilterTwoSelections,
 )
+from dodal.devices.beamlines.i02_1.fast_grid_scan import ZebraFastGridScanTwoD
+from dodal.devices.beamlines.i02_1.sample_motors import SampleMotors
 from dodal.devices.eiger import EigerDetector
-from dodal.devices.i02_1.fast_grid_scan import ZebraFastGridScanTwoD
-from dodal.devices.i02_1.sample_motors import SampleMotors
 from dodal.devices.synchrotron import Synchrotron
 from dodal.devices.zebra.zebra import Zebra
 from dodal.devices.zebra.zebra_constants_mapping import (

src/dodal/beamlines/i03.py

@@ -17,6 +17,10 @@
 from dodal.devices.attenuator.attenuator import BinaryFilterAttenuator
 from dodal.devices.backlight import Backlight
 from dodal.devices.baton import Baton
+from dodal.devices.beamlines.i03 import Beamstop
+from dodal.devices.beamlines.i03.beamsize import Beamsize
+from dodal.devices.beamlines.i03.dcm import DCM
+from dodal.devices.beamlines.i03.undulator_dcm import UndulatorDCM
 from dodal.devices.collimation_table import CollimationTable
 from dodal.devices.cryostream import (
     CryoStreamGantry,
@@ -31,10 +35,6 @@
 from dodal.devices.flux import Flux
 from dodal.devices.focusing_mirror import FocusingMirrorWithStripes, MirrorVoltages
 from dodal.devices.hutch_shutter import HutchShutter
-from dodal.devices.i03 import Beamstop
-from dodal.devices.i03.beamsize import Beamsize
-from dodal.devices.i03.dcm import DCM
-from dodal.devices.i03.undulator_dcm import UndulatorDCM
 from dodal.devices.ipin import IPin
 from dodal.devices.motors import XYZStage
 from dodal.devices.oav.oav_detector import OAVBeamCentreFile

src/dodal/beamlines/i04.py

@@ -11,18 +11,18 @@
 from dodal.devices.attenuator.attenuator import BinaryFilterAttenuator
 from dodal.devices.backlight import Backlight
 from dodal.devices.baton import Baton
+from dodal.devices.beamlines.i03.dcm import DCM
+from dodal.devices.beamlines.i04.beam_centre import CentreEllipseMethod
+from dodal.devices.beamlines.i04.beamsize import Beamsize
+from dodal.devices.beamlines.i04.constants import RedisConstants
+from dodal.devices.beamlines.i04.max_pixel import MaxPixel
+from dodal.devices.beamlines.i04.murko_results import MurkoResultsDevice
+from dodal.devices.beamlines.i04.transfocator import Transfocator
 from dodal.devices.detector.detector_motion import DetectorMotion
 from dodal.devices.diamond_filter import DiamondFilter, I04Filters
 from dodal.devices.eiger import EigerDetector
 from dodal.devices.fast_grid_scan import ZebraFastGridScanThreeD
 from dodal.devices.flux import Flux
-from dodal.devices.i03.dcm import DCM
-from dodal.devices.i04.beam_centre import CentreEllipseMethod
-from dodal.devices.i04.beamsize import Beamsize
-from dodal.devices.i04.constants import RedisConstants
-from dodal.devices.i04.max_pixel import MaxPixel
-from dodal.devices.i04.murko_results import MurkoResultsDevice
-from dodal.devices.i04.transfocator import Transfocator
 from dodal.devices.ipin import IPin
 from dodal.devices.motors import XYZStage
 from dodal.devices.mx_phase1.beamstop import Beamstop

src/dodal/beamlines/i05_shared.py

@@ -1,5 +1,5 @@
 from dodal.device_manager import DeviceManager
-from dodal.devices.i05.enums import Grating
+from dodal.devices.beamlines.i05.enums import Grating
 from dodal.devices.insertion_device import (
     Apple2,
     UndulatorGap,

src/dodal/beamlines/i06_1.py

@@ -11,6 +11,7 @@
 PREFIX = BeamlinePrefix(BL, suffix="J")
 set_log_beamline(BL)
 set_utils_beamline(BL)
+
 devices = DeviceManager()
 devices.include(i06_shared_devices)