dls-dodal 1.56.0__tar.gz → 1.57.0__tar.gz

{dls_dodal-1.56.0 → dls_dodal-1.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dls-dodal
-Version: 1.56.0
+Version: 1.57.0
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>, Joseph Ware <joseph.ware@diamond.ac.uk>, Oliver Silvester <Oliver.Silvester@diamond.ac.uk>, Noemi Frisina <noemi.frisina@diamond.ac.uk>
 License:                                  Apache License
@@ -215,7 +215,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async[ca,pva]>=0.13.0
+Requires-Dist: ophyd-async[ca,pva]>=0.13.2
 Requires-Dist: bluesky==1.14.2
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json

{dls_dodal-1.56.0 → dls_dodal-1.57.0}/conftest.py

@@ -15,7 +15,7 @@ from ophyd_async.core import (
     PathProvider,
 )
 from tests.devices.i10.test_data import LOOKUP_TABLE_PATH
-from tests.devices.unit_tests.test_daq_configuration import MOCK_DAQ_CONFIG_PATH
+from tests.devices.test_daq_configuration import MOCK_DAQ_CONFIG_PATH
 from tests.test_data import (
     TEST_DISPLAY_CONFIG,
     TEST_OAV_ZOOM_LEVELS_XML,

dls_dodal-1.57.0/docs/explanations/decisions/0006-devices-shared-between-endstations.md

@@ -0,0 +1,27 @@
+# 6. Handle devices shared between multiple endstations
+
+Date: 2025-08-27
+
+## Status
+
+Proposed
+
+## Context
+
+Some beamlines have multiple endstations with shared hardware in the optics or experiment hutch, and could potentially be trying to control it at the same time. Any device in the common hutch should only be fully controlled by one endstation at a time - the one that is taking data - but still be readable from the other endstations.
+
+## Decision
+
+The current solution is to have a separate blueapi instance for the shared hutch in order to be able to control the access to all the devices defined there.
+For all hardware in the shared optics hutch, the architecture should follow this structure:
+
+- There is a base device in dodal that sends a REST call to the shared blueapi with plan and devices names, as well as the name of the endstation performing the call.
+- There are read-only versions of the shared devices in the endstation blueapi which inherit from the base device above and set up the request parameters.
+- The real settable devices are only defined in the shared blueapi and should never be called directly from a plan.
+- The shared blueapi instance also has an ``AccessControl`` device that reads the endstation in use for beamtime from a PV.
+- Every plan should then be wrapped in a decorator that reads the ``AccessControl`` device, check which endstation is making the request and only allows the plan to run if the two values match.
+
+
+:::{seealso}
+[Optics hutch implementation on I19](https://diamondlightsource.github.io/i19-bluesky/main/explanations/decisions/0004-optics-blueapi-architecture.html) for an example.
+:::

dls_dodal-1.56.0/docs/how-to/create-beamline.rst → dls_dodal-1.57.0/docs/how-to/create-beamline.md

@@ -1,13 +1,11 @@
-Creating a new beamline
-=======================
+# Creating a new beamline
 
 A beamline is a collection of devices that can be used together to run experiments, they may be read-only or capable of being set.
 They include motors in the experiment hutch, optical components in the optics hutch, the synchrotron "machine" and more.
 
-Beamline Modules
-----------------
+## Beamline Modules
 
-Each beamline should have its own file in the ``dodal.beamlines`` folder, in which the particular devices for the 
+Each beamline should have its own file in the ``dodal.beamlines`` folder, in which the particular devices for the
 beamline are instantiated. The file should be named after the colloquial name for the beamline. For example:
 
 * ``i03.py``
@@ -16,14 +14,14 @@ beamline are instantiated. The file should be named after the colloquial name fo
 
 Beamline modules (in ``dodal.beamlines``) are code-as-configuration. They define the set of devices and common device
 settings needed for a particular beamline or group of similar beamlines (e.g. a beamline and its digital twin). Some
-of our tooling depends on the convention of *only* beamline modules going in this package. Common utilities should 
+of our tooling depends on the convention of *only* beamline modules going in this package. Common utilities should
 go somewhere else e.g. ``dodal.utils`` or ``dodal.beamlines.common``.
 
 The following example creates a fictitious beamline ``w41``, with a simulated twin ``s41``.
 ``w41`` needs to monitor the status of the Synchrotron and has an AdAravisDetector.
 ``s41`` has a simulated clone of the AdAravisDetector, but not of the Synchrotron machine.
 
-.. code-block:: python
+```python
 
     from ophyd_async.epics.adaravis import AravisDetector
 
@@ -85,3 +83,4 @@ The following example creates a fictitious beamline ``w41``, with a simulated tw
             drv_suffix=CAM_SUFFIX,
             fileio_suffix=HDF5_SUFFIX,
         )
+```

dls_dodal-1.57.0/docs/how-to/move-code.md

@@ -0,0 +1,94 @@
+
+# Moving code from another repo
+
+In the process of writing code in other DLS repos you may come to realise that it makes more sense to be in ``dodal``. It is a good idea to keep the history for this code, you can do this by doing the following (we will be using moving devices from https://github.com/DiamondLightSource/hyperion as an example):
+
+* Clone the codebase you are copying from:
+
+```bash
+    git clone git@github.com:DiamondLightSource/hyperion.git clone_for_history
+    cd clone_for_history/
+```
+
+* Remove the remote to avoid any mistaken pushes:
+
+```bash
+    git remote rm origin
+```
+
+* Filter out only the directory/file you want to move:
+
+```bash
+    pip install git-filter-repo
+    git-filter-repo --path file/to/move --path /other/file/to/move -f
+```
+
+* Clean everything up:
+
+```bash
+    git reset --hard
+    git gc --aggressive
+    git prune
+    git clean -fd
+```
+
+* Add a note to every commit message to mention it's been moved::
+
+```bash
+    git filter-branch --msg-filter 'sed "$ a \
+    NOTE: Commit originally came from https://github.com/DiamondLightSource/hyperion"' -f -- --all
+```
+
+* If you have been using Github [issue references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issues-and-pull-requests) in the old repository modify these to point to be more explicit (Note that this assumes the old repo uses ``#123`` notation and only ever references issues from it's own repo)::
+
+```bash
+    git filter-branch -f --msg-filter 'sed "s|#[0-9]\+|DiamondLightSource/hyperion&|g"' -- --all
+```
+
+* Prepare the code to be in the correct structure for dodal::
+
+```bash
+    mkdir -p src/dodal/devices
+    mv path/to/device src/dodal/devices/
+```
+
+* At this point it's a good idea to check the log ``git log`` and the general directory structure to ensure it looks mostly correct
+
+* Add and commit this (locally)::
+
+```bash
+    git add .
+    git commit -m "Prepare for import into dodal"
+```
+
+* In a different folder clone ``dodal``, remove the origin (for now) to be safe and create a branch::
+
+```bash
+    git clone git@github.com:DiamondLightSource/dodal.git
+    cd dodal
+    git remote rm origin
+    git checkout -b add_code_from_hyperion
+```
+
+* Add the source repo as a remote for ``dodal``::
+
+```bash
+    git remote add source /path/to/source/old_repo/.git
+```
+
+* Pull from the source repo::
+
+```bash
+    git pull --no-rebase source main --allow-unrelated-histories
+```
+
+* This is another point where it's a good idea to check the log ``git log`` and the general directory structure to ensure it looks mostly correct
+
+* Remove the source remote and re-add origin::
+
+```bash
+    git remote rm source
+    git remote add origin git@github.com:DiamondLightSource/dodal.git
+```
+
+* Tidy up the code so that it fits into the ``dodal`` repo e.g. in the Hyperion case we had to change the tests to import from ``hyperion`` to import from ``dodal`` and add some more dependencies.

{dls_dodal-1.56.0 → dls_dodal-1.57.0}/docs/how-to/write-tests.md

@@ -7,6 +7,9 @@ Testing is essential to maintain the integrity and reliability of the codebase.
 - **Unit Tests**: Place unit tests for individual components in the `tests` directory, but take care to mirror the file structure of the `src` folder with the corresponding code files. Use the `test_*.py` naming convention for test files.
 - **System Tests**: Tests that interact with DLS infrastructure, network, and filesystem should be placed in the top-level `systems_test` folder. This separation ensures that these tests are easily identifiable and can be run independently from unit tests.
 
+Useful functions for testing that can be reused across multiple tests for common devices and for external plan repositories belong in the `dodal/testing` directory. For example, when mocking a `Motor` device, all of the signals will default to zero, which will cause errors when trying to move. The `patch_motor` and `patch_all_motors` functions, found in `dodal.testing`, will populate the mocked motor with useful default values for the signals so that it can still be used in tests.
+
+
 ## Writing a test for a device
 We aim for high test coverage in dodal with small, modular test functions. To achieve this, we need to test the relevant methods by writing tests for the class/method we are creating or changing, checking for the expected behaviour. We shouldn't need to write tests for parent classes unless we alter their behaviour.
 

dls_dodal-1.56.0/docs/how-to/zocalo.rst → dls_dodal-1.57.0/docs/how-to/zocalo.md

@@ -1,32 +1,27 @@
-Zocalo Interaction
-==================
+# Zocalo Interaction
 
-.. image:: ../assets/zocalo.png
-  :alt: Diagram of zocalo
+![Diagram of zocalo](../assets/zocalo.png)
 
-Zocalo jobs are triggered based on their ISPyB DCID using the ``ZocaloTrigger`` class in a callback subscribed to the 
-Bluesky plan or ``RunEngine``. These can trigger processing for any kind of job, as zocalo infers the necessary 
+Zocalo jobs are triggered based on their ISPyB DCID using the ``ZocaloTrigger`` class in a callback subscribed to the
+Bluesky plan or ``RunEngine``. These can trigger processing for any kind of job, as zocalo infers the necessary
 processing from data in ISPyB.
 
-Results are received using the ``ZocaloResults`` device, so that they can be read into a plan and used for 
-decision-making. Currently the ``ZocaloResults`` device is only made to handle X-ray centring results. It subscribes to 
+Results are received using the ``ZocaloResults`` device, so that they can be read into a plan and used for
+decision-making. Currently the ``ZocaloResults`` device is only made to handle X-ray centring results. It subscribes to
 a given zocalo RabbitMQ channel the first time that it is triggered.
 
-Zocalo Service
-==============
+# Zocalo Service
 
-The Zocalo service processes incoming messages using recipes which describe routing of messages between processing 
-steps. You can see `source for the recipes here`_.
-
-.. _source for the recipes here: https://gitlab.diamond.ac.uk/scisoft/zocalo/-/tree/master/recipes
+The Zocalo service processes incoming messages using recipes which describe routing of messages between processing
+steps. You can see [source for the recipes here](https://gitlab.diamond.ac.uk/scisoft/zocalo/-/tree/master/recipes).
 
 You can find more information about Zocalo at https://confluence.diamond.ac.uk/display/SSCC/How+to+create+an+MX+processing+pipeline
 
-Gridscans
----------
+## Gridscans
 
-The Zocalo Service receives messages of the following form for both the xy and xz gridscans::
+The Zocalo Service receives messages of the following form for both the xy and xz gridscans:
 
+```
     {
         'recipes': ['mimas'],
         'parameters': {
@@ -39,9 +34,11 @@ The Zocalo Service receives messages of the following form for both the xy and x
             'guid': 'd6f117bb-c856-4df8-b9bc-2d3c625e9fd5'
         }
     }
+```
 
-Zocalo is then sent stop messages::
+Zocalo is then sent stop messages:
 
+```
    {
         'recipes': ['mimas'],
         'parameters': {
@@ -50,22 +47,22 @@ Zocalo is then sent stop messages::
             'guid': '9a96e59c-da30-494c-8380-c7a5c828c2c9'
         },
    }
+```
 
 these tell zocalo that the data is now ready to be processed.
 
 Zocalo then uses the ISPyB DataCollection ID to fetch the corresponding info from ISPyB
 
-The messages that zocalo receives can be found in Graylog in the Zocalo stream, from there you can find the log of 
+The messages that zocalo receives can be found in Graylog in the Zocalo stream, from there you can find the log of
 the recipe processing using the path to the logbook that comes from messages like these::
     Message saved in logbook at /dls/tmp/zocalo/dispatcher/2024-12/cb/62d35b-7cc9-4f1b-868b-712e82aa0271
 
-From the zocalo graylog you can also see that once the gridscan nexus file is picked up (for the CPU gridscan) it 
-starts a recipe::
+From the zocalo graylog you can also see that once the gridscan nexus file is picked up (for the CPU gridscan) it
+starts a recipe:
 
+```
     {'recipes': ['per-image-analysis-gridscan-i03-no-really'], 'parameters': {'ispyb_dcid': 16085803, 'filename': '{filename}', 'start_frame_index': '{start_frame_index}', 'number_of_frames': '{number_of_frames}', 'message_index': '{message_index}', 'guid': 'd10f8b8c-57a5-4dc4-acaf-a22f8d2bbf60'}, 'recipe': <workflows.recipe.recipe.Recipe object at 0x7f0587f13110>}
+```
 
-
-If you look at the recipe json, Zocalo then runs Per-Image-Analysis on each frame and then assembles the results in 
-the `DLS X-Ray Centring service`_.
-
-.. _DLS X-Ray Centring service: https://github.com/DiamondLightSource/python-dlstbx/blob/a8fcbd30335bf13f5e35df78badfc60397500535/src/dlstbx/services/xray_centering.py
+If you look at the recipe json, Zocalo then runs Per-Image-Analysis on each frame and then assembles the results in
+the [DLS X-Ray Centring service](https://github.com/DiamondLightSource/python-dlstbx/blob/a8fcbd30335bf13f5e35df78badfc60397500535/src/dlstbx/services/xray_centering.py).

dls_dodal-1.56.0/docs/reference/device-standards.rst → dls_dodal-1.57.0/docs/reference/device-standards.md

@@ -1,46 +1,40 @@
-Device Standards
-================
+# Device Standards
 
-Ophyd vs Ophyd-async
---------------------
-Some devices have been written in ``ophyd`` for historic reasons. However, all new devices should be written in 
-``ophyd-async`` and any old ``ophyd`` devices undergoing a large re-write should be considered for 
-conversion to ``ophyd-async``. 
+## Ophyd vs Ophyd-async
 
+Some devices have been written in ``ophyd`` for historic reasons. However, all new devices should be written in
+``ophyd-async`` and any old ``ophyd`` devices undergoing a large re-write should be considered for
+conversion to ``ophyd-async``.
 
-.. _where_to_put_devices:
 
-Where to put devices
---------------------
+## Where to put devices
 
-Dodal is written with the philosophy that Ophyd devices should be assumed to be as generic as possible. I.e. you 
+Dodal is written with the philosophy that Ophyd devices should be assumed to be as generic as possible. I.e. you
 should think about where to place them in the following order:
 
-#. A device that could be used at any facility, e.g. a generic ``Motor`` or a commercial product with a 
+*  A device that could be used at any facility, e.g. a generic ``Motor`` or a commercial product with a
    standard IOC, should go in https://github.com/bluesky/ophyd-async
-#. A device that may be on any beamline should go in the top level of the ``devices`` folder. If it is a quite 
+*  A device that may be on any beamline should go in the top level of the ``devices`` folder. If it is a quite
    complex device (e.g. multiple files) it should have a folder of its own e.g. ``oav``
-#. A device that is very specific to a particular beamline should go in the ``devices/ixx`` folder
+*  A device that is very specific to a particular beamline should go in the ``devices/ixx`` folder
 
-This is in an effort to avoid duplication across facilities/beamlines. You should also consider whether it is best for a piece of logic is better suited to the control system or a bluesky plan - see `ophyd-async's guide <https://blueskyproject.io/ophyd-async/main/explanations/where-device-logic.html>`_ on that.
+This is in an effort to avoid duplication across facilities/beamlines. You should also consider whether it is best for a piece of logic is better suited to the control system or a bluesky plan - see [ophyd-async's guide](https://blueskyproject.io/ophyd-async/main/explanations/where-device-logic.html) on that.
 
 Determining where in dodal a device should live can be summarised below:
 
-.. image:: ../assets/where-to-put-dodal-logic.png
+![Dodal logic](../assets/where-to-put-dodal-logic.png)
 
-Device Best Practices
-----------------------------
+## Device Best Practices
 
-Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
+Ophyd-async directory contains a [flowchart](https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html) for a simplified decision tree about what interfaces
 should a given device implement. In addition to this the following guidelines are strongly recommended:
 
-#. Device should have their name as an optional str parameter with a default of ""- this allows ophyd-async to automatically name the device
-#. Devices should contain only the PV suffixes that are generic for any instance of the device. See `PV Suffixes`_
-#. Anything in a device that is expected to be set externally should be a signal. See `Use of signals`_
-#. Devices should not hold state, when they are read they should read the hardware. See `Holding State`_
+* Device should have their name as an optional str parameter with a default of ""- this allows ophyd-async to automatically name the device
+* Devices should contain only the PV suffixes that are generic for any instance of the device. See [PV Suffixes](#pv-suffixes)
+* Anything in a device that is expected to be set externally should be a signal. See [Use of signals](#use-of-signals)
+* Devices should not hold state, when they are read they should read the hardware. See [Holding State](#holding-state)
 
-Defaulting Names
-----------------
+## Defaulting Names
 
 Device should provide the ability to override their name while maintaining a default name of ""-
 this allows the device to be named on connection from the name of its factory function when using
@@ -48,7 +42,7 @@ the device_factory decorator.
 
 When a device is named in this way, all of its child devices are named appropriately.
 
-.. code-block:: python
+```python
     class MyDevice(Device):
         def __init__(self, prefix: str, name: str = "")
             x = Motor(prefix + "X")
@@ -61,50 +55,50 @@ When a device is named in this way, all of its child devices are named appropria
     f = foo()
     f.name == "foo"
     f.x.name == "foo-x"
+```
 
-PV Suffixes
------------
+## PV Suffixes
 
 In general devices should contain only the PV suffixes that are generic for any instance of the device e.g.
 
-.. code-block:: python
+```python
 
     class MyDevice(Device):
         def __init__(self, prefix: str, name: str = "")
             self.bragg = Motor(prefix + "BRAGG")
-            super().__init__(name)  
+            super().__init__(name)
 
-    MyDevice("BLXXI-MO-DCM-01:")      
+    MyDevice("BLXXI-MO-DCM-01:")
+```
 
 is preferred over
 
-.. code-block:: python
+```python
 
     class MyDevice(Device):
         def __init__(self, prefix: str, name: str = "")
             self.bragg = Motor(prefix + "-MO-DCM-01:BRAGG")
-            super().__init__(name)        
+            super().__init__(name)
 
     MyDevice("BLXXI")
+```
 
 This is so that a new device on say ``-MO-DCM-02`` can be easily created.
 
-Beamline Prefix
----------------
+## Beamline Prefix
 
-Most devices have a beamline-specific prefix such as BL03I however some devices do not. In such cases when calling 
-`device_instantiation()` you can specify `bl_prefix=False` to ensure that the beamline prefix is not automatically 
+Most devices have a beamline-specific prefix such as BL03I however some devices do not. In such cases when calling
+`device_instantiation()` you can specify `bl_prefix=False` to ensure that the beamline prefix is not automatically
 prepended.
 
-Use of signals
---------------
+## Use of signals
 
-Anything in a device that is expected to be set externally e.g. by a plan should be a signal, even if it does not 
-connect to EPICS. If it does not connect to EPICS it should be a soft signal. 
+Anything in a device that is expected to be set externally e.g. by a plan should be a signal, even if it does not
+connect to EPICS. If it does not connect to EPICS it should be a soft signal.
 
 Whilst it would be possible to do:
 
-.. code-block:: python
+```python
 
     class MyDevice(Device):
         def __init__(self):
@@ -113,6 +107,7 @@ Whilst it would be possible to do:
     my_device = MyDevice()
     def my_plan():
         my_device.param = "new_value"
+```
 
 this has potential negative side effects:
 
@@ -122,19 +117,19 @@ this has potential negative side effects:
 
 Instead you should make a soft signal:
 
-.. code-block:: python
-    
+```python
+
     class MyDevice(Device):
         def __init__(self):
              self.param = soft_signal_rw(str)
-    
+
     my_device = MyDevice()
     def my_plan():
         yield from bps.mv(my_device.param, "new_value")
+```
 
 
-Holding State
--------------
+## Holding State
 
 Devices should avoid holding state as much as possible. Ophyd devices are mostly trying to reflect the state of hardware and so when the device is read that hardware should be read.
 
@@ -145,7 +140,7 @@ If the device holds the state itself it is likely to not reflect the real hardwa
 
 For example, if I have a device that I would like to treat as moving in/out based on an underlying axis then it would be incorrect to implement it like this:
 
-.. code-block:: python
+```python
 
     class InOut(Enum):
         IN = 0
@@ -156,7 +151,7 @@ For example, if I have a device that I would like to treat as moving in/out base
             self.underlying_motor = Motor("MOTOR")
             with self.add_children_as_readables():
                 self.in_out, self._in_out_setter = soft_signal_r_and_setter(InOut)
-                
+
 
         @AsyncStatus.wrap
         async def set(self, value: InOut):
@@ -165,11 +160,12 @@ For example, if I have a device that I would like to treat as moving in/out base
             else:
                 await self.underlying_motor.set(0)
             self._in_out_setter(value)
+```
 
 While this may appear to work fine during normal operation the state of in_out is only ever updated if the ophyd device is set. It is incorrect to assume that underlying_motor only changes
 based on this and so this has the issues listed above. Instead you should make sure to update in_out whenever the device is read e.g.
 
-.. code-block:: python
+```python
 
     class InOut(Enum):
         IN = 0
@@ -180,7 +176,7 @@ based on this and so this has the issues listed above. Instead you should make s
             self.underlying_motor = Motor("MOTOR")
             with self.add_children_as_readables():
                 self.in_out = derived_signal_r(self._get_in_out_from_hardware, current_position= self.underlying_motor)
-                
+
         def _get_in_out_from_hardware(self, current_position:float)->InOut:
             if isclose(current_position, 0):
                 return InOut.IN
@@ -196,7 +192,6 @@ based on this and so this has the issues listed above. Instead you should make s
                 await self.underlying_motor.set(100)
             else:
                 await self.underlying_motor.set(0)
+```
 
-For detail on how to use derived signal see `ophyd-async how to guide. <https://blueskyproject.io/ophyd-async/main/how-to/derive-one-signal-from-others.html>`__
-
-.. _flowchart: https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html
+For detail on how to use derived signal see [ophyd-async how to guide](https://blueskyproject.io/ophyd-async/main/how-to/derive-one-signal-from-others.html).

dls_dodal-1.56.0/docs/reference/standards.rst → dls_dodal-1.57.0/docs/reference/standards.md

@@ -1,46 +1,36 @@
-Standards
-=========
+# Standards
 
 This document defines the code and documentation standards used in this
 repository.
 
-Code Standards
---------------
+## Code Standards
 
 The code in this repository conforms to standards set by the following tools:
 
-- ruff_ for code formatting
-- flake8_ for style checks
-- isort_ for import ordering
-- pyright_ for static type checking
+- [ruff](https://docs.astral.sh/ruff/) for code formatting
+- [flake8](https://flake8.pycqa.org/en/latest/) for style checks
+- [isort](https://pycqa.github.io/isort/) for import ordering
+- [pyright](https://github.com/microsoft/pyright) for static type checking
 
-.. seealso::
+:::{seealso}
+How-to guides [how-to/lint](../how-to/lint) and [how-to/statis-analysis](../how-to/static-analysis)
+:::
 
-    How-to guides `../how-to/lint` and `../how-to/static-analysis`
+## Supported Python Versions
 
-.. _ruff: https://docs.astral.sh/ruff/
-.. _flake8: https://flake8.pycqa.org/en/latest/
-.. _isort: https://pycqa.github.io/isort/
-.. _pyright: https://github.com/microsoft/pyright
-
-Supported Python Versions
--------------------------
-
-As a standard for the python versions to support, we should be matching the deprecation policy at 
+As a standard for the python versions to support, we should be matching the deprecation policy at
 https://numpy.org/neps/nep-0029-deprecation_policy.html.
 
 Currently supported versions are: 3.11, 3.12, 3.13. (As of the last edit of this document.)
 
-.. _documentation_standards:
 
-Documentation Standards
------------------------
+## Documentation Standards
 
 Docstrings are pre-processed using the Sphinx Napoleon extension. As such,
-google-style_ is considered as standard for this repository. Please use type
+[google-style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#google-vs-numpy) is considered as standard for this repository. Please use type
 hints in the function signature for types. For example:
 
-.. code:: python
+```python
 
     def func(arg1: str, arg2: int) -> bool:
         """Summary line.
@@ -55,14 +45,14 @@ hints in the function signature for types. For example:
             Description of return value
         """
         return True
-
-.. _google-style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#google-vs-numpy
+```
 
 Documentation is contained in the ``docs`` directory and extracted from
 docstrings of the API.
 
-Docs follow the underlining convention::
+Docs follow the underlining convention:
 
+```
     Headling 1 (page title)
     =======================
 
@@ -71,7 +61,8 @@ Docs follow the underlining convention::
 
     Heading 3
     ~~~~~~~~~
+```
 
-.. seealso::
-
-    How-to guide `../how-to/build-docs`
+:::{seealso}
+How-to guide [how-to/build-docs](../how-to/build-docs)
+:::

dls_dodal-1.57.0/docs/tutorials/get_started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+## The Purpose of Dodal
+
+``dodal`` provides set of [ophyd](https://nsls-ii.github.io/ophyd/)/[ophyd-async](https://blueskyproject.io/ophyd-async/main/index.html) devices and [bluesky](https://blueskyproject.io/bluesky/) plans that are commonly useful across many beamlines at DLS.
+
+If you have some code that you think would be useful to be added please do so!
+
+## Using Devices
+
+``dodal`` contains devices to cover anything you would like to do using a beamline's hardware.
+
+To use these devices you can do the following:
+
+```python
+from dodal.beamlines import i03
+dcm = i03.dcm()
+# You can now use the DCM as you would any other device in Bluesky plans
+```
+
+If you are on a beamline workstation this will give you immediate access to the real hardware. If you are not on a
+beamline workstation it will default to connecting to a simulated instrument.
+
+## Adding Logging
+
+``dodal`` provides some helper functions to help you log what's going on.
+
+You can set these up using:
+
+```python
+from dodal.beamlines import i03
+from dodal.log import set_up_logging_handlers, LOGGER
+
+set_up_logging_handlers()
+```
+
+Some logging will now occur when you are using devices/plans, you can increase the amount of logs by
+instead using ``set_up_logging_handlers("DEBUG")``. You can also log more explicitly using:
+
+```python
+LOGGER.info("I am a log message")
+```
+
+
+If you are on a beamline workstation this will save any logs to ``dls_sw/BEAMLINE/logs/bluesky/`` and will
+push them to [graylog](https://graylog-log-target.diamond.ac.uk/search). If you are not on a beamline workstation logs will be saved next to your working directory
+and pushed to a local graylog instance.
+
+If you would like to only log to graylog/file exlusively there are helper functions in ``dodal.log`` that you can use.

{dls_dodal-1.56.0 → dls_dodal-1.57.0}/pyproject.toml

@@ -14,7 +14,7 @@ description = "Ophyd devices and other utils that could be used across DLS beaml
 dependencies = [
     "click",
     "ophyd",
-    "ophyd-async[ca,pva]>=0.13.0",
+    "ophyd-async[ca,pva]>=0.13.2",
     "bluesky==1.14.2",  # https://github.com/bluesky/bluesky/issues/1938
     "pyepics",
     "dataclasses-json",