Merge branch 'main' into hyperion_1439_cache_lower_gonio

.gitignore

@@ -57,6 +57,7 @@ tmp/
 
 # Sphinx documentation
 docs/_build/
+docs/user/reference/generated/
 
 # PyBuilder
 target/

docs/_templates/autosummary/class.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      {% if item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {% if item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+      {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,67 @@
+{{ fullname | escape | underline}}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block classes %}
+{% if classes %}
+.. currentmodule:: {{ module }}
+.. rubric:: {{ _('Classes') }}
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in classes %}
+   ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+

docs/conf.py

@@ -5,6 +5,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import sys
+from inspect import isclass
 from pathlib import Path
 from subprocess import check_output
 
@@ -32,6 +33,7 @@
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -44,6 +46,10 @@
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    # for the mermaid diagrams#
+    "sphinxcontrib.mermaid",
+    # Signatures from type hinting
+    "sphinx_autodoc_typehints",
 ]
 
 # If true, Sphinx will warn about all references where the target cannot
@@ -65,6 +71,7 @@
     ("py:class", "typing_extensions.Literal"),
 ]
 
+
 # Both the class’ and the __init__ method’s docstring are concatenated and
 # inserted into the main body of the autoclass directive
 autoclass_content = "both"
@@ -74,6 +81,11 @@
 
 # Don't inherit docstrings from baseclasses
 autodoc_inherit_docstrings = False
+autodoc_class_signature = "separated"
+autodoc_preserve_defaults = True
+
+autosummary_generate = True
+autosummary_imported_members = False
 
 # Output graphviz directive produced images in a scalable format
 graphviz_output_format = "svg"
@@ -83,15 +95,15 @@
 default_role = "any"
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".py"]
 
 # The master toctree document.
 master_doc = "index"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # These patterns also affect html_static_path and html_extra_path
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "conf.py"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -192,3 +204,27 @@
 # Logo
 html_logo = "images/dls-logo.svg"
 html_favicon = "images/dls-favicon.ico"
+
+templates_path = ["_templates"]
+
+# options for sphinx-autodoc-typehints
+always_document_param_types = True
+typehints_use_signature = True
+typehints_use_signature_return = True
+typehints_defaults = "comma"
+
+
+def skip_module_classes(app, what, name, obj, skip, options):
+    if name.startswith("_"):
+        # NB would like to include overridden dunder-methods in docs but
+        # sphinx insists on randomly including inherited ones which do not
+        # appear in inherited_members and thus are impossible to exclude
+        return True
+    if what == "module" and isclass(obj):
+        return True
+
+    return skip
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_module_classes)

docs/user/how-to/create-beamline.rst → docs/developer/how-to/create-beamline.rst

@@ -1,9 +1,24 @@
 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
+----------------
+
+Each beamline should have its own file in the ``doodal.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``
+* ``i04_1.py``
+* ``vmxi.py``
+
+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 
+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.

docs/developer/how-to/make-new-ophyd-async-device.md → docs/developer/how-to/make-new-ophyd-async-device.rst

@@ -1,18 +1,21 @@
-# Decision Flowchart for Creating a New ophyd_async Device
+Decision Flowchart for Creating a New ophyd_async Device
+========================================================
 
-This document contains decision flowcharts designed to guide developers through the process of creating a new device in the Dodal library. That is done using [ophyd-async](https://github.com/bluesky/ophyd-async) framework, the standard hardware abstraction library at Diamond. These flowcharts help in determining the appropriate class inheritance, methods to override, and testing procedures for optimal device functionality and integration into the system.
+This document contains decision flowcharts designed to guide developers through the process of creating a new device in the Dodal library. 
+That is done using `ophyd-async`_ framework, the standard hardware abstraction library at Diamond. These flowcharts help in determining the appropriate class inheritance, methods to override, and testing procedures for optimal device functionality and integration into the system.
 
-## High-Level Development Flowchart
+High-Level Development Flowchart
+--------------------------------
 
 The **objective** is to get it into main and then test it on the beamline! Ensuring fast iteration. You write the device, you assume you know how it works, you write tests against those assumptions, you merge. Then and only then do you test your assumptions on the beamline. If they were wrong, that's more issues.
 
-See if you can find a similar device that someone has already made. If one seems to exists but has different PV names, those can and should be changed. Advise consulting with controls. If the device is urgently needed, two copies can coexist but there must be an issue to reconcile.
+See if you can find a similar device that someone has already made. If one seems to exist but has different PV names, those can and should be changed. Advise consulting with controls. If the device is urgently needed, two copies can coexist but there must be an issue to reconcile.
 
 You might find the dodal CLI useful to verify the PV values.
 
-There's some of this already but more general advise not to do this task alone. Consult before starting, seek feedback early (e.g. draft PR) and merge with other people's devices where possible. The test suite should provide the confidence to do so without breaking anything.
+There's some of this already but more general advice not to do this task alone. Consult before starting, seek feedback early (e.g. draft PR) and merge with other people's devices where possible. The test suite should provide the confidence to do so without breaking anything.
 
-```{mermaid}
+.. mermaid::
 
   flowchart TD
     highLevelStart([Start]) --> createIssue[Create Issue for New Device]
@@ -31,17 +34,17 @@ There's some of this already but more general advise not to do this task alone.
     adviseConsultControls -- "Urgent need for device" --> createIssueForReconciliation[Create an issue to reconcile two versions later]
     createIssueForReconciliation --> testPVs
 
-```
+Interface Selection Flowchart
+-----------------------------
 
-## Interface Selection Flowchart
+See the chart in `ophyd-async`_.
 
-See the chart in [ophyd-async](https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html)
-
-## Testing Flowchart
+Testing Flowchart
+-----------------
 
 This flowchart outlines the testing procedure for the new ophyd_async device, from creating fixtures to testing state transitions and hardware integration.
 
-```{mermaid}
+.. mermaid::
 
   flowchart TD
     testStart([Start Testing]) --> checkExistingFixtures[Check for existing fixtures]
@@ -55,9 +58,10 @@ This flowchart outlines the testing procedure for the new ophyd_async device, fr
     decision -- "No" --> modifyCode[Modify code and update tests]
     modifyCode --> createFixtures
 
+Additional Notes
+----------------
 
-```
+- ``with self.add_children_as_readables():`` Ensure this context manager is used appropriately in the device implementation to add child components as readable properties, but not Movables.
 
-## Additional Notes
 
-- `with self.add_children_as_readables():` Ensure this context manager is used appropriately in the device implementation to add child components as readable properties, but not Movables.
+.. _ophyd-async: https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html

docs/developer/how-to/make-release.rst

@@ -1,16 +1,31 @@
 Make a release
 ==============
 
+Releases are created through the Github release interface.
+
 To make a new release, please follow this checklist:
 
-- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/)
+- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/) (The release version should 
+  look like ``{major}.{minor}.{patch}``). See `Deciding release numbers`_ if you're unsure on what the release version
+  should be.
 - Go to the GitHub release_ page
 - Choose ``Draft New Release``
 - Click ``Choose Tag`` and supply the new tag you chose (click create new tag)
-- Click ``Generate release notes``, review and edit these notes
-- Choose a title and click ``Publish Release``
+- Click ``Generate release notes``, review and edit these notes. Confirm they do not omit anything important and make sense (to a user, not just a developer).
+- Choose a title and click ``Publish Release``. This will create a release on ``pypi`` automatically and post to the 
+  ``bluesky`` slack channel.
+- Manually confirm that the ``pypi`` version has been updated (after all tests have run) and that slack is notified.
 
 Note that tagging and pushing to the main branch has the same effect except that
 you will not get the option to edit the release notes.
 
 .. _release: https://github.com/DiamondLightSource/dodal/releases
+
+Deciding release numbers
+------------------------
+
+Releases should obviously be versioned higher than the previous latest release. Otherwise you should follow this guide:
+
+* **Major** - Changes that have the potential to break plans
+* **Minor** - New features
+* **Patch** - Bug fixes

docs/developer/how-to/zocalo.rst

@@ -0,0 +1,13 @@
+Zocalo Interaction
+==================
+
+.. image:: ../../assets/zocalo.png
+  :alt: Diagram of zocalo
+
+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 
+a given zocalo RabbitMQ channel the first time that it is triggered.

docs/developer/index.rst

@@ -29,10 +29,13 @@ side-bar.
             how-to/move-code
             how-to/build-docs
             how-to/run-tests
+            how-to/make-new-ophyd-async-device
             how-to/static-analysis
             how-to/lint
             how-to/update-tools
             how-to/make-release
+            how-to/create-beamline
+            how-to/zocalo
 
         +++
 
@@ -57,6 +60,7 @@ side-bar.
             :maxdepth: 1
 
             reference/standards
+            reference/device-standards
 
         +++