WIP

bluesky · Jan 21, 2025 · f68f00c · f68f00c
1 parent 20b4aa7
commit f68f00c
Show file tree

Hide file tree

Showing 46 changed files with 1,017 additions and 659 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -20,6 +20,7 @@
                 "editor.codeActionsOnSave": {
                     "source.organizeImports": "explicit"
                 },
+                "remote.autoForwardPorts": false,
                 "[python]": {
                     "editor.defaultFormatter": "charliermarsh.ruff"
                 }
@@ -38,7 +39,7 @@
     },
     "features": {
         // add in eternal history and other bash features
-        "ghcr.io/diamondlightsource/devcontainer-features/bash-config:1.0.0": {}
+        "ghcr.io/diamondlightsource/devcontainer-features/bash-config:1": {}
     },
     // Create the config folder for the bash-config feature
     "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/bash-config",

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,5 @@
+/* allow a wider screen so we can fit 88 chars of source code on it */
+.bd-page-width {
+    max-width: 100rem;
+    /* default is 88rem */
+}
diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst
@@ -1,8 +1,3 @@
-.. note::
-
-    Ophyd async is considered experimental until the v1.0 release and
-    may change API on minor release numbers before then
-
 {{ ('``' + fullname + '``') | underline }}
 
 {%- set filtered_members = [] %}

diff --git a/docs/conf.py b/docs/conf.py
@@ -72,6 +72,7 @@
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
+# TODO: turn this back on
 # nitpicky = True
 
 # A list of (type, target) tuples (by default empty) that should be ignored when
@@ -98,7 +99,7 @@
 autodoc_inherit_docstrings = False
 
 # Add some more modules to the top level autosummary
-ophyd_async.__all__ += ["sim", "epics", "tango", "fastcs", "plan_stubs"]
+ophyd_async.__all__ += ["sim", "epics", "tango", "fastcs", "plan_stubs", "testing"]
 
 # Document only what is in __all__
 autosummary_ignore_module_all = False
@@ -137,6 +138,7 @@
     "numpy": ("https://numpy.org/devdocs/", None),
     "databroker": ("https://blueskyproject.io/databroker/", None),
     "event-model": ("https://blueskyproject.io/event-model/main", None),
+    "pytest": ("https://docs.pytest.org/en/stable/", None),
 }
 
 # A dictionary of graphviz graph attributes for inheritance diagrams.
@@ -230,6 +232,10 @@
 html_logo = "images/ophyd-async-logo.svg"
 html_favicon = "images/ophyd-favicon.svg"
 
+# Custom CSS
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
 # If False and a module has the __all__ attribute set, autosummary documents
 # every member listed in __all__ and no others. Default is True
 autosummary_ignore_module_all = False

diff --git a/docs/examples/epics_demo.py b/docs/examples/epics_demo.py
diff --git a/docs/explanations/declarative-vs-procedural.md b/docs/explanations/declarative-vs-procedural.md
@@ -0,0 +1,36 @@
+# Declarative vs Procedural Devices
+
+Ophyd async has two styles of creating Devices, Declarative and Procedural. This article describes why there are two mechanisms for building Devices, and looks at the pros and cons of each style.
+
+## Procedural style
+
+The procedural style mirrors how you would create a traditional python class, you define an `__init__` method, add some class members, then call the superclass `__init__` method. In the case of ophyd async those class members are likely to be Signals and other Devices. For example, in the `ophyd_async.sim.SimMotor` we create its soft signal children in an `__init__` method:
+```{literalinclude} ../../src/ophyd_async/sim/_motor.py
+:start-after: class SimMotor
+:end-before: def set_name
+```
+It is explicit and obvious, but verbose. It also allows you to embed arbitrary python logic in the creation of signals, so is required for making soft signals and DeviceVectors with contents based on an argument passed to `__init__`. It also allows you to use the [](#StandardReadable.add_children_as_readables) context manager which can save some typing.
+
+## Declarative style
+
+The declarative style mirrors how you would create a pydantic `BaseModel`. You create type hints to tell the base class what type of object you create, add annotations to tell it some parameters on how to create it, then the base class `__init__` will introspect and create them. For example, in the `ophyd_async.fastcs.panda.PulseBlock` we define the members we expect, and the baseclass will introspect the selected FastCS transport (EPICS IOC or Tango Device Server) and connect them, adding any extras that are published:
+```{literalinclude} ../../src/ophyd_async/fastcs/panda/_block.py
+:pyobject: PulseBlock
+```
+For a traditional EPICS IOC there is no such introspection mechanism, so we require a PV Suffix to be supplied via an [annotation](#typing.Annotated). For example, in `ophyd_async.epics.demo.DemoPointDetectorChannel` we describe the PV Suffix and whether the signal appears in `read()` or `read_configuration()` using [](#typing.Annotated):
+```{literalinclude} ../../src/ophyd_async/epics/demo/_point_detector_channel.py
+:pyobject: DemoPointDetectorChannel
+```
+It is compact and has the minimum amount of boilerplate, but is limited in its scope to what sorts of Signals and Devices the base class can create. It also requires the usage of a [](#StandardReadableFormat) for each Signal if using [](#StandardReadable) which may be more verbose than the procedural approach. It is best suited for introspectable FastCS and Tango devices, and repetitive EPICS Devices that are wrapped into larger Devices like areaDetectors.
+
+## Grey area
+
+There is quite a large segment of Devices that could be written both ways, for instance `ophyd_async.epics.demo.DemoMotor`. This could be written in either style with roughly the same legibility, so is a matter of taste:
+```{literalinclude} ../../src/ophyd_async/epics/demo/_motor.py
+:start-after: class DemoMotor
+:end-before: def set_name
+```
+
+## Conclusion
+
+Ophyd async supports both the declarative and procedural style, and is not prescriptive about which is used. In the end the decision is likely to come down to personal taste, and the style of the surrounding code.
diff --git a/docs/explanations/design-goals.rst → docs/explanations/design-goals.md b/docs/explanations/design-goals.rst → docs/explanations/design-goals.md
diff --git a/docs/explanations/event-loop-choice.rst → ...lanations/device-connection-strategies.md b/docs/explanations/event-loop-choice.rst → ...lanations/device-connection-strategies.md
@@ -1,11 +1,13 @@
-Device Collector Event-Loop Choice
-----------------------------------
+# Device connection strategies
+
+There are various ways you can connect an ophyd-async Device, depending on whether you are running under a RunEngine or not. This article details each of those modes and why you might want to connect in that mode
+
+## Up front connection 
 
 In a sync context, the ophyd-async :python:`init_devices` requires the bluesky event-loop
 to connect to devices. In an async context, it does not.
 
-Sync Context
-============
+## Sync Context
 
 In a sync context the run-engine must be initialized prior to connecting to devices.
 We enfore usage of the bluesky event-loop in this context.
@@ -22,8 +24,7 @@ The following will fail if :python:`RE = RunEngine()` has not been called alread
 The :python:`init_devices` connects to devices in the event-loop created in the run-engine.
 
 
-Async Context
-=============
+## Async Context
 
 In an async context device connection is decoupled from the run-engine.
 The following attempts connection to all the devices in the :python:`init_devices`

diff --git a/docs/how-to/choose-interfaces-for-devices.md → docs/how-to/choose-right-baseclass.md b/docs/how-to/choose-interfaces-for-devices.md → docs/how-to/choose-right-baseclass.md
diff --git a/docs/how-to/compound-devices.rst b/docs/how-to/compound-devices.rst
diff --git a/docs/how-to/make-a-standard-detector.rst → docs/how-to/implement-ad-detector.md b/docs/how-to/make-a-standard-detector.rst → docs/how-to/implement-ad-detector.md
diff --git a/...ow-to/use_set_and_wait_for_other_value.md → docs/how-to/interact-with-signals.md b/...ow-to/use_set_and_wait_for_other_value.md → docs/how-to/interact-with-signals.md
diff --git a/docs/how-to/make-a-simple-device.rst b/docs/how-to/make-a-simple-device.rst
diff --git a/docs/how-to/write-tests-for-devices.rst b/docs/how-to/write-tests-for-devices.rst
diff --git a/docs/tutorials.md b/docs/tutorials.md
@@ -6,5 +6,8 @@ Tutorials for installation and typical usage. New users start here.
 :maxdepth: 1
 :glob:
 
-tutorials/*
+tutorials/installation
+tutorials/using-devices
+tutorials/implementing-devices
+tutorials/writing-tests-for-devices
 ```