From 8a75fd6bb67d2d249101f0fe1eea500295c90e37 Mon Sep 17 00:00:00 2001 From: Henry Pinkard <7969470+henrypinkard@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:16:19 -0400 Subject: [PATCH] more documenation; added APIs --- docs/apis.rst | 46 +++++++++++++++++++ docs/conf.py | 2 + docs/extending/add_devices.rst | 2 +- docs/index.rst | 1 + docs/requirements.txt | 2 + docs/usage.rst | 2 +- docs/usage/backends.rst | 10 ++-- ..._ram_backend.rst => ndstorage_backend.rst} | 5 +- docs/usage/devices.rst | 2 +- docs/usage/installation.rst | 2 - .../{key_concepts.rst => key_features.rst} | 4 +- src/exengine/kernel/ex_future.py | 20 ++++---- src/exengine/kernel/executor.py | 6 +-- src/exengine/kernel/notification_base.py | 1 + 14 files changed, 78 insertions(+), 27 deletions(-) create mode 100644 docs/apis.rst rename docs/usage/backends/{ndtiff_and_ram_backend.rst => ndstorage_backend.rst} (79%) rename docs/usage/{key_concepts.rst => key_features.rst} (78%) diff --git a/docs/apis.rst b/docs/apis.rst new file mode 100644 index 0000000..a5ac3df --- /dev/null +++ b/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: diff --git a/docs/conf.py b/docs/conf.py index 1066bcf..254c8c8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,8 @@ extensions = [ 'sphinx_rtd_theme', 'sphinx_togglebutton', + 'sphinx.ext.autodoc', + 'sphinx_autodoc_typehints', # for better type hint support ] diff --git a/docs/extending/add_devices.rst b/docs/extending/add_devices.rst index 339e08b..c6b16b0 100644 --- a/docs/extending/add_devices.rst +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index cf11eaa..1b0af06 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,3 +36,4 @@ Key Features: design usage extending + apis diff --git a/docs/requirements.txt b/docs/requirements.txt index 615a0e5..34e2573 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,5 @@ sphinx +sphinx-autodoc-typehints sphinx-rtd-theme sphinx-togglebutton +sphinx_autodoc_typehints diff --git a/docs/usage.rst b/docs/usage.rst index 0144b6b..35bf8d9 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -9,4 +9,4 @@ Usage usage/installation usage/backends - usage/key_concepts \ No newline at end of file + usage/key_features \ No newline at end of file diff --git a/docs/usage/backends.rst b/docs/usage/backends.rst index b3a7f72..8ffe9ab 100644 --- a/docs/usage/backends.rst +++ b/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 diff --git a/docs/usage/backends/ndtiff_and_ram_backend.rst b/docs/usage/backends/ndstorage_backend.rst similarity index 79% rename from docs/usage/backends/ndtiff_and_ram_backend.rst rename to docs/usage/backends/ndstorage_backend.rst index 94a5d51..0de39f5 100644 --- a/docs/usage/backends/ndtiff_and_ram_backend.rst +++ b/docs/usage/backends/ndstorage_backend.rst @@ -1,4 +1,4 @@ -.. _NDTiff and RAM backend: +.. _ndstorage_backend: ################################################################## NDTiff and RAM backend @@ -6,9 +6,6 @@ NDTiff and RAM backend `NDTiff `_ 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 `_ 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 diff --git a/docs/usage/devices.rst b/docs/usage/devices.rst index dce1098..d834c99 100644 --- a/docs/usage/devices.rst +++ b/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 diff --git a/docs/usage/installation.rst b/docs/usage/installation.rst index b5b1aa9..97baa1e 100644 --- a/docs/usage/installation.rst +++ b/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: diff --git a/docs/usage/key_concepts.rst b/docs/usage/key_features.rst similarity index 78% rename from docs/usage/key_concepts.rst rename to docs/usage/key_features.rst index c5da42c..7164d51 100644 --- a/docs/usage/key_concepts.rst +++ b/docs/usage/key_features.rst @@ -1,7 +1,7 @@ -.. _key concepts: +.. _key_features: ============ -Key concepts +Key features ============ .. toctree:: diff --git a/src/exengine/kernel/ex_future.py b/src/exengine/kernel/ex_future.py index 9975c24..cd8227d 100644 --- a/src/exengine/kernel/ex_future.py +++ b/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) diff --git a/src/exengine/kernel/executor.py b/src/exengine/kernel/executor.py index 1b05139..ccd6a66 100644 --- a/src/exengine/kernel/executor.py +++ b/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. diff --git a/src/exengine/kernel/notification_base.py b/src/exengine/kernel/notification_base.py index 3c2342e..b47343a 100644 --- a/src/exengine/kernel/notification_base.py +++ b/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"