Add deprecation warning to inject

docs/how-to/include-devices-in-plans.md

@@ -0,0 +1,60 @@
+# Include Devices in Plans
+
+There are three main ways to include dodal devices in plans
+
+## 1. Pass as Argument
+
+```python
+import bluesky.plans as bp
+
+from bluesky.protocols import Readable
+from bluesky.utils import MsgGenerator
+from dodal.beamlines import i22
+
+def my_plan(detector: Readable) -> MsgGenerator:
+    yield from bp.count([detector])
+
+RE(my_plan(i22.saxs()))
+```
+
+This is useful for generic plans that can run on a variety of devices and are not designed with any specific device in mind.
+
+## 2. Pass as Default Argument
+
+```python
+import bluesky.plans as bp
+
+from bluesky.protocols import Readable
+from bluesky.utils import MsgGenerator
+from dodal.beamlines import i22
+
+def my_plan(detector: Readable = i22.saxs(connect_immediately=False)) -> MsgGenerator:
+    yield from bp.count([detector])
+
+RE(my_plan()))
+```
+
+This is useful for plans that will usually, but not exclusively, use the same device.
+
+## 3. Instantiate Within the Plan
+
+```python
+import bluesky.plans as bp
+import ophyd_async.plan_stubs as ops
+
+from bluesky.protocols import Readable
+from bluesky.utils import MsgGenerator
+from dodal.beamlines import i22
+
+def my_plan() -> MsgGenerator:
+    detector = i22.saxs(connect_immediately=False)
+    # We need to connect via the stub instead of directly 
+    # so that the RunEngine performs the connection in the
+    # correct event loop
+    yield from ops.ensure_connected(detector)
+    yield from bp.count([detector])
+
+RE(my_plan()))
+```
+
+This is useful for plans that are designed to only ever work with a specific device.

src/dodal/common/coordination.py

@@ -1,4 +1,6 @@
 import uuid
+import warnings
+from textwrap import dedent
 from typing import Any
 
 from dodal.common.types import Group
@@ -37,4 +39,22 @@ def scan(x: Movable = inject("stage_x"), start: float = 0.0 ...)
 
     """
 
+    warnings.warn(
+        dedent("""
+        Inject is deprecated, users are now expected to call the device factory
+        functions in dodal directly, these will cache devices as singletons after
+        they have been called once. For example:
+
+        from bluesky.protocols import Readable
+        from bluesky.utils import MsgGenerator
+        from dodal.beamlines import i22
+
+        def my_plan(detector: Readable = i22.saxs(connect_immediately=False)) -> MsgGenerator:
+            ...
+
+        Where previously the default would have been inject("saxs")
+        """),
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return name

tests/common/test_coordination.py

@@ -17,11 +17,23 @@ def test_group_uid(group: str):
 
 
 def test_type_checking_ignores_inject():
-    def example_function(x: Movable = inject("foo")) -> MsgGenerator:  # noqa: B008
-        yield from {}
-
-    # These asserts are sanity checks
-    # the real test is whether this test passes type checking
-    x: Parameter = signature(example_function).parameters["x"]
-    assert x.annotation == Movable
-    assert x.default == "foo"
+    with pytest.raises(DeprecationWarning):
+
+        def example_function(x: Movable = inject("foo")) -> MsgGenerator:  # noqa: B008
+            yield from {}
+
+        # These asserts are sanity checks
+        # the real test is whether this test passes type checking
+        x: Parameter = signature(example_function).parameters["x"]
+        assert x.annotation == Movable
+        assert x.default == "foo"
+
+
+def test_inject_is_deprecated():
+    with pytest.raises(
+        DeprecationWarning,
+        match="Inject is deprecated, users are now expected to call the device factory",
+    ):
+
+        def example_function(x: Movable = inject("foo")) -> MsgGenerator:  # noqa: B008
+            yield from {}