update docs

docs/developer/general/explanations/decisions/0002-repository-structure.rst

@@ -0,0 +1,46 @@
+2. mx-bluesky repository structure
+==================================
+
+Date: 2024-08-21
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+Initially, we wanted to separate "application code" such as hyperion from "library code" generic over MX beamlines belonging in ``mx-bluesky``. 
+However, as these were developed together and also together with ``dodal``, dependency management became impossible.
+
+Decision
+--------
+
+We will stick to a monorepo repository structure as follows:
+
+.. code-block:: text
+
+    mx_bluesky/
+    ├-src/
+    | └-mx_bluesky/
+    |   ├-common/               # Plan stubs, utilities, and other common code
+    |   ├-beamlines/
+    |   | ├-i03/
+    |   | ├-i04/
+    |   | └-i24/
+    |   |   └-serial/           # Plans for one beamline go in the respective module
+    |   └-hyperion/             # Plans for more than one beamline go in the top level
+    ├-tests/
+    | ├-unit_tests/                             # Tests are separated into "unit_tests" and "system_tests"
+    | | └-{mirror of mx_bluesky structure}/     # Where the former refers to tests which can be run without
+    | ├-system_tests/                           # access to external services, and the latter might need
+    | | └-{mirror of mx_bluesky structure}/     # to talk to ISPyB, the DLS filesystem, etc.
+    | └-test_data/
+    └-docs/
+      ├-developer/
+      └-user/
+
+To preserve some of the benefits we would have had from separate repositories, code from beamline or "application" 
+modules (e.g. ``mx_bluesky.i24.serial`` or ``mx_bluesky.hyperion``) may import from ``mx_bluesky.common`` but not 
+the other way around - this should be enforced with a check in CI.

docs/developer/general/explanations/decisions/0003-python-version-support.rst

@@ -0,0 +1,29 @@
+1. Python version support
+=========================
+
+Date: 2024-08-22
+
+Status
+------
+
+Accepted
+
+Context
+-------
+
+We need to decide which versions of python we will support. We want to be able to make use of new python features,
+and reduce the number of different supported versions, but we also want scientists in a variety of environments to
+be able to use the code in this repository. At the time of writing this, we merged https://github.com/DiamondLightSource/hyperion
+into this repository. It only supported python 3.11, while ``mx-bluesky`` at this time supported 3.10 and 3.11.
+
+Decision
+--------
+
+We will support no older python version than described in https://numpy.org/neps/nep-0029-deprecation_policy.html
+We may if appropriate choose to drop python versions before they are dropped by that schedule. Instead
+of modifying ``hyperion`` to work with python 3.10, we are dropping support for it at the time of writing this.
+
+Consequences
+------------
+
+We must always support at least the newest major python version, and most likely several versions behind it, but no version older than 42 months.

docs/developer/hyperion/index.rst

@@ -0,0 +1,20 @@
+General MX-Bluesky Developer Guide
+==================================
+
+Documentation is split into four categories, and each is also accessible from links in the side-bar.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: :material-regular:`description;3em`
+
+        .. toctree::
+            :caption: Reference
+            :maxdepth: 1
+
+            reference/param-hierarchy
+            reference/readme
+
+        +++
+
+        Technical reference material on standards in use.

docs/developer/hyperion/reference/param-hierarchy.rst

@@ -0,0 +1,4 @@
+Hyperion Parameter class hierarchy
+==================================
+
+TODO: automate including the param hierarchy here

pyproject.toml

@@ -39,7 +39,7 @@ dependencies = [
     # These dependencies may be issued as pre-release versions and should have a pin constraint
     # as by default pip-install will not upgrade to a pre-release.
     # 
-    "blueapi == 0.4.4",
+    "blueapi == 0.4.5a1",
     "daq-config-server >= 0.1.1",
     "ophyd == 1.9.0",
     "ophyd-async >= 0.3a5",
@@ -78,6 +78,7 @@ dev = [
     "ruff",
     "sphinx-autobuild",
     "sphinx-copybutton",
+    "sphinxcontrib-plantuml",
     "sphinx-design",
     "tox-direct",
     "tox",