More documentation

docs/apis.rst

@@ -0,0 +1,46 @@
+==============
+API Reference
+==============
+
+ExecutionEngine
+================
+
+.. autoclass:: exengine.kernel.executor.ExecutionEngine
+   :members:
+   :exclude-members: register_device
+
+
+.. autoclass:: exengine.kernel.ex_future.ExecutionFuture
+   :members:
+
+
+
+Data
+=====
+
+.. autoclass:: exengine.kernel.data_storage_base.DataStorage
+   :members:
+
+.. autoclass:: exengine.kernel.data_coords.DataCoordinates
+
+.. autoclass:: exengine.kernel.data_coords.DataCoordinatesIterator
+   :members:
+
+.. autoclass:: exengine.kernel.data_handler.DataHandler
+   :members:
+
+
+Base classes for extending ExEngine
+===================================
+
+.. autoclass:: exengine.device_types.Device
+   :members:
+
+.. autoclass:: exengine.kernel.ex_event_base.ExecutorEvent
+   :members:
+
+.. autoclass:: exengine.kernel.notification_base.Notification
+   :members:
+
+.. autoclass:: exengine.kernel.data_storage_base.DataStorage
+   :members:

docs/conf.py

@@ -19,6 +19,8 @@
 extensions = [
     'sphinx_rtd_theme',
     'sphinx_togglebutton',
+    'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',  # for better type hint support
 ]
 
 

docs/extending/add_devices.rst

@@ -1,7 +1,7 @@
 .. _add_devices:
 
 ##############################
-Adding Support for New Devices
+Adding New Device Backends
 ##############################
 
 We welcome contributions of new device backends to ExEngine! If you've developed a backend for a new device, framework, or system, please consider submitting a Pull Request.

docs/index.rst

@@ -1,9 +1,9 @@
-#####################################################
-ExEngine: An execution engine for microscope control
-#####################################################
+############################################################################
+ExEngine: an execution engine for microscope and laboratory hardware control
+############################################################################
 
 
-ExEngine is a versatile toolkit for microscopy hardware control and data acquisition, bridging low-level hardware control with high-level experiment design and user interfaces. It empowers researchers to create sophisticated microscopy experiments without getting bogged down in details, while scaling to support advanced automated and AI-driven workflows across various microscopy applications.
+ExEngine is a pure Python toolkit for building microscopy and laboratory hardware control software. Unlike application-specific software that provide tightly integrated device access, control logic, and user interfaces,ExEngine is a flexible intermediary which enables mixing and matching of components from different frameworks within a single application. This approach allows researchers to build custom software that meets their specific needs, without being limited to vertically integrated software stacks.
 
 Key Features:
 ==============
@@ -36,3 +36,4 @@ Key Features:
    design
    usage
    extending
+   apis

docs/requirements.txt

@@ -1,3 +1,5 @@
 sphinx
+sphinx-autodoc-typehints
 sphinx-rtd-theme
 sphinx-togglebutton
+sphinx_autodoc_typehints

docs/usage.rst

@@ -9,4 +9,4 @@ Usage
 
    usage/installation
    usage/backends
-   usage/key_concepts
+   usage/key_features

docs/usage/backends.rst

@@ -1,20 +1,24 @@
 .. _backends:
 
 ================
-Device Backends
+Backends
 ================
 
 This page contains a list of supported backends for ExEngine, as well as information and setup instructions for each
 
+
+Device Backends
+---------------
+
+
 .. toctree::
    :maxdepth: 1
 
    backends/micro-manager_backend
 
 
-================
 Storage Backends
-================
+----------------
 
 .. toctree::
    :maxdepth: 1

docs/usage/backends/ndtiff_and_ram_backend.rst → docs/usage/backends/ndstorage_backend.rst

@@ -1,14 +1,11 @@
-.. _NDTiff and RAM backend:
+.. _ndstorage_backend:
 
 ##################################################################
 NDTiff and RAM backend
 ##################################################################
 
 `NDTiff <https://github.com/micro-manager/NDStorage>`_ is a high-performance indexed Tiff format used to save image data in Micro-Manager. NDRAM is a light-weight in-memory storage class. Both implementations provide the same API for in-memory (NDRAMStorage) or file-based (NDTiffStorage) storage.
 
-`NDTiff <https://github.com/micro-manager/NDStorage>`_ is a high-performance, indexed Tiff format that can be written to local disk or network storage. It is one of the formats used in Micro-Manager. NDRAM is a simple in-memory storage. Both share the same API, enabling easy switching between file-based and in-memory storage.
-
-
 To install this backend:
 
 .. code-block:: bash

docs/usage/devices.rst

@@ -68,7 +68,7 @@ By default, all ExEngine devices are made thread-safe.
 
 This is done under the hood by intercepting and rerouting all device calls to common threads.
 
-This can be turned off by setting the `no_executor` parameter to `True` when initializing a device:
+This can be turned off by setting the ``no_executor`` parameter to ``True`` when initializing a device:
 
 .. code-block:: python
 

docs/usage/installation.rst

@@ -3,8 +3,6 @@
 Installation and Setup
 ======================
 
-Basic Installation
-------------------
 ExEngine was design to support multiple device and data storage backends, either independently or in combination. Each backend has some adapter code that lives within the Exengine package, and (optionally) other dependencies that need to be installed separately.
 
 To install ExEngine with all available backend adapters, use pip:

docs/usage/key_concepts.rst → docs/usage/key_features.rst

@@ -1,7 +1,7 @@
-.. _key concepts:
+.. _key_features:
 
 ============
-Key concepts
+Key features
 ============
 
 .. toctree::

src/exengine/kernel/ex_future.py

@@ -109,27 +109,27 @@ def abort(self, await_completion: bool = False):
     ####################################################################################################################
 
     def await_data(self, coordinates: Optional[Union[DataCoordinates, Dict[str, Union[int, str]],
-                                               DataCoordinatesIterator, Sequence[DataCoordinates],
-                                               Sequence[Dict[str, Union[int, str]]]]],
+    DataCoordinatesIterator, Sequence[DataCoordinates],
+    Sequence[Dict[str, Union[int, str]]]]],
                    return_data: bool = False, return_metadata: bool = False,
                    processed: bool = False, stored: bool = False):
         """
         (Only for AcquisitionEvents that also inherit from DataProducing)
         Block until the event's data is acquired/processed/saved, and optionally return the data/metadata.
-        when waiting for the data to be acquired (i.e. before it is processed), since there is no way to guarantee that
+        When waiting for the data to be acquired (i.e. before it is processed), since there is no way to guarantee that
         this function is called before the data is acquired, the data may have already been saved and not readily
         available in RAM. In this case, the data will be read from disk.
 
         Args:
-            coordinates: A single DataCoordinates object/dictionary, or Sequence (i.e. list or tuple) of DataCoordinates
-             objects/dictionaries. If None, this function will block until the next data is acquired/processed/saved
+            coordinates: A single DataCoordinates object/dictionary, or Sequence (i.e. list or tuple) of
+            DataCoordinates objects/dictionaries. If None, this function will block until the next data is
+            acquired/processed/saved
             return_data: whether to return the data
             return_metadata: whether to return the metadata
-            processed: whether to wait until data has been processed. If not data processor is in use,
-                then this parameter has no effect
-            stored: whether to wait for data that has been stored. If the call to await data occurs before the
-              data gets passed off to the storage_backends class, then it will be stored in memory and returned immediately.
-              without having to retrieve
+            processed: whether to wait until data has been processed. If not data processor is in use, then this
+            parameter has no effect
+            stored: whether to wait for data that has been stored. If the call to await data occurs before the data
+            gets passed off to the storage_backends class, then it will be stored in memory and returned immediately without having to retrieve
         """
 
         coordinates_iterator = DataCoordinatesIterator.create(coordinates)

src/exengine/kernel/executor.py

@@ -191,7 +191,7 @@ def submit(self, event_or_events: Union[ExecutorEvent, Iterable[ExecutorEvent]],
         - Priority execution can be requested using the 'prioritize' parameter.
 
         Parameters:
-        ----------
+        -----------
         event_or_events : Union[ExecutorEvent, Iterable[ExecutorEvent]]
             A single ExecutorEvent or an iterable of ExecutorEvents to be submitted.
 
@@ -212,14 +212,14 @@ def submit(self, event_or_events: Union[ExecutorEvent, Iterable[ExecutorEvent]],
             Object to handle data and metadata produced by DataProducingExecutorEvents.
 
         Returns:
-        -------
+        --------
         Union[AcquisitionFuture, Iterable[AcquisitionFuture]]
             For a single event: returns a single AcquisitionFuture.
             For multiple events: returns an Iterable of AcquisitionFutures.
             Note: The number of returned futures may differ from the input if transpilation occurs.
 
         Notes:
-        -----
+        ------
         - Transpilation may optimize multiple events, potentially altering their number or structure.
         - Use 'prioritize' for critical system changes that should occur before other queued events.
         - 'use_free_thread' is essential for operations that need to run independently, like cancellation events.

src/exengine/kernel/notification_base.py

@@ -34,6 +34,7 @@ class Notification(ABC, Generic[TNotificationPayload]):
 
     @dataclass
     class DataAcquired(Notification[DataCoordinates]):
+
         # Define the category and description of the notification shared by all instances of this class
         category = NotificationCategory.Data
         description = "Data has been acquired by a camera or other data-producing device and is now available"