diff --git a/docs/source/api_reference/api_reference.md b/docs/source/api_reference/api_reference.md index dea38e3a..8ab65a78 100644 --- a/docs/source/api_reference/api_reference.md +++ b/docs/source/api_reference/api_reference.md @@ -1,3 +1,4 @@ +(api_reference)= # API Reference ```{eval-rst} diff --git a/docs/source/assets/bec_widgets_glance.png b/docs/source/assets/bec_widgets_glance.png new file mode 100644 index 00000000..dec616c0 Binary files /dev/null and b/docs/source/assets/bec_widgets_glance.png differ diff --git a/docs/source/assets/portrait_48dp.svg b/docs/source/assets/portrait_48dp.svg new file mode 100644 index 00000000..affd8dc7 --- /dev/null +++ b/docs/source/assets/portrait_48dp.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/assets/precision_manufacturing_48dp.svg b/docs/source/assets/precision_manufacturing_48dp.svg new file mode 100644 index 00000000..b9c70507 --- /dev/null +++ b/docs/source/assets/precision_manufacturing_48dp.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/assets/rocket_launch_48dp.svg b/docs/source/assets/rocket_launch_48dp.svg new file mode 100644 index 00000000..1cd031b9 --- /dev/null +++ b/docs/source/assets/rocket_launch_48dp.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/assets/timeline_48dp.svg b/docs/source/assets/timeline_48dp.svg new file mode 100644 index 00000000..11eb4a6e --- /dev/null +++ b/docs/source/assets/timeline_48dp.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/assets/toc_48dp.svg b/docs/source/assets/toc_48dp.svg new file mode 100644 index 00000000..79f90e58 --- /dev/null +++ b/docs/source/assets/toc_48dp.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/source/developer/developer.md b/docs/source/developer/developer.md index c0677608..1eaa268b 100644 --- a/docs/source/developer/developer.md +++ b/docs/source/developer/developer.md @@ -17,33 +17,64 @@ glossary/ ``` *** -**Developer Documentation for BEC** -Here, we aim to provide you with all the essential information to kickstart your journey with BEC. From understanding the intricate architecture to contributing effectively to the project, we've got you covered. Explore the following key topics: +````{grid} 2 +:gutter: 5 -* [Architecture](#developer.architecture): Gain insights into the underlying structure of BEC. -* [Contributing](#developer.contributing): Learn how to actively participate and contribute to the development of BEC. -* [Installing Developer Environment](#developer.install_developer_env): Set up your developer environment to work with BEC. -* [Developing with Visual Studio Code](#developer.vscode): Learn how to set up Visual Studio Code for developing Python applications and how to use it to work with BEC. -* [Logging](#developer.logging): Understand how to use the logger in BEC and monitor log messages in real-time. -* [BEC Command Line Interface (CLI)](#developer.bec_cli): Explore the command-line tool and customize its behaviour. -* [BEC Simulation Framework](#developer.bec_sim): The simulation framework allows you to explore, test or develop within the BEC ecosystem with direct feedback. -* [BEC Graphical User Interface (GUI)](#developer.bec_gui): Learn how to use the graphical user interface to interact with BEC and explore how to create your own GUIs. -* [BEC Configuration](#developer.bec_config): Learn about the different ways of customizing BEC to your needs. -* [Data Access](#developer.data_access): Explore different ways of accessing data acquired with BEC. -* [Event Data](#developer.data_access): Explore the handling of event data in BEC to streamline your data analysis and live feedback. -* [Ophyd](#developer.ophyd): Familiarize yourself with Ophyd, the underlying library for device control in BEC, and learn how to integrate and work with Ophyd devices in the BEC context. -* [External Sources](#developer.external_sources): Understand how to incorporate external data sources into your BEC workflow. -* [BEC Plugins](#developer.bec_plugins): Learn how to create and use plugins to extend BEC's functionality and tailor it to your needs. -* [Scans](#developer.scans): Dive into the world of scans in BEC, understand the basic structure of a scan, and learn how to create a scan plugin. -* [Writing tests](#developer.tests): how to write tests for your code, and usage information about BEC fixtures -* [Glossary](#developer.glossary): Refer to a glossary of terms used throughout the BEC documentation. -* [Reference](#developer.reference): Access a comprehensive reference of all BEC classes, functions, and methods. +```{grid-item-card} +:link: developer.getting_started +:link-type: ref +:img-top: /assets/rocket_launch_48dp.svg +:text-align: center +## Getting Started -We invite you to embark on your BEC development journey, empowering you to contribute to this dynamic project and tailor it to the unique requirements of your experiments. Happy coding! +Learn about BEC's architecture, contribute to the project, set up your developer environment, and develop new features for BEC using plugins. +``` +```{grid-item-card} +:link: developer.devices +:link-type: ref +:img-top: /assets/precision_manufacturing_48dp.svg +:text-align: center +## Devices +No matter if you need to add new devices to BEC or modify existing ones, this section provides information on how to configure and use devices in BEC. +``` +```{grid-item-card} +:link: developer.scans +:link-type: ref +:img-top: /assets/timeline_48dp.svg +:text-align: center + +## Scans + +Understand the basic structure of a scan in BEC and learn how to create a scan plugin to extend BEC's functionality and furthe tailor it to your needs. + +``` + +```{grid-item-card} +:link: developer.user_interfaces +:link-type: ref +:img-top: /assets/portrait_48dp.svg +:text-align: center + +## User Interfaces + +Discover and learn how to contribute to the command-line tool and graphical user interface for interacting with BEC. +``` + +```{grid-item-card} +:link: developer.glossary +:link-type: ref +:img-top: /assets/toc_48dp.svg +:text-align: center + +## Glossary + +Refer to a glossary of terms used throughout the BEC documentation. +``` +```` \ No newline at end of file diff --git a/docs/source/developer/devices/device_configuration.md b/docs/source/developer/devices/device_configuration.md index 9a0d83ec..87d99a6b 100644 --- a/docs/source/developer/devices/device_configuration.md +++ b/docs/source/developer/devices/device_configuration.md @@ -21,6 +21,8 @@ curr: softwareTrigger: false ``` +More examples of device configurations can be found in the [Ophyd devices repository](https://gitlab.psi.ch/bec/ophyd_devices/-/tree/main/ophyd_devices/configs). + The following sections explain the different parts of the device configuration in more detail. * **deviceClass** \ diff --git a/docs/source/developer/devices/devices.md b/docs/source/developer/devices/devices.md index 7cb6fb06..613936e0 100644 --- a/docs/source/developer/devices/devices.md +++ b/docs/source/developer/devices/devices.md @@ -1,10 +1,16 @@ (developer.devices)= # Devices +Whether new devices need to be added to BEC or existing devices need to be modified, the daily operation of beamlines at large-scale facilities depends on the ability change the behavior and configuration of devices. This section provides information on how to configure and use devices in BEC. + +After an introduction to the [Ophyd libary](ophyd/ophyd.md), the section [device configuration](device_configuration/device_configuration.md) explains how to configure devices in BEC and how to load new configs. + +A dedicated section on the [BEC simulation framework](bec_sim/bec_sim.md) explains how to simulate devices in BEC, either for testing or for development purposes. Finally, a section on [external sources](external_sources/external_sources.md) explains how to deal with external data sources in BEC. ```{toctree} --- maxdepth: 2 +hidden: true --- ophyd/ device_configuration/ diff --git a/docs/source/developer/getting_started/architecture.md b/docs/source/developer/getting_started/architecture.md index 848ed793..12dc2c3e 100644 --- a/docs/source/developer/getting_started/architecture.md +++ b/docs/source/developer/getting_started/architecture.md @@ -20,7 +20,7 @@ The scan worker executes the scan instructions and if necessary publishes device ## Device Server This service provides a thin layer on top of Bluesky’s Ophyd library to support remote procedure calls (RPC) through Redis. It listens to device instructions sent to Redis and performs the specified operations on [Ophyd objects](#developer.ophyd). -The available Ophyd objects are determined by loading a device configuration, either through the client, e.g., through yaml files, or from the connected database. +The available Ophyd objects are determined by loading a [device configuration](#developer.ophyd_device_config), typically by loading a YAML file from the command-line interface. Providing Ophyd objects through a service layer also facilitates sharing access to devices that require a direct socket connection, bypassing the EPICS layer. ## Scan Bundler diff --git a/docs/source/developer/getting_started/getting_started.md b/docs/source/developer/getting_started/getting_started.md index 97ee02ef..e7d07328 100644 --- a/docs/source/developer/getting_started/getting_started.md +++ b/docs/source/developer/getting_started/getting_started.md @@ -1,3 +1,4 @@ +(developer.getting_started)= # Getting started This section provides a step-by-step guide to help you get started with developing for BEC. Whether you are new to BEC or an experienced developer, this guide will help you set up your development environment, understand the architecture of BEC, and contribute effectively to the project. diff --git a/docs/source/developer/scans/scans.md b/docs/source/developer/scans/scans.md index e1a4c280..952133ae 100644 --- a/docs/source/developer/scans/scans.md +++ b/docs/source/developer/scans/scans.md @@ -9,7 +9,7 @@ A scan in BEC is a Python class that inherits from the `ScanBase` class and impl :icon: code-square :animate: fade-in-slide-down -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase ``` @@ -17,7 +17,7 @@ A scan in BEC is a Python class that inherits from the `ScanBase` class and impl The order of execution is defined by the `run` method, which is called by the scan server. By default, the `run` method calls the following methods in the following order: -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase.run ``` @@ -37,7 +37,7 @@ After reading out the current scan motor positions with `read_scan_motors`, the The default implementation of the `prepare_positions` method in the `ScanBase` class is as follows: -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase.prepare_positions ``` @@ -51,7 +51,7 @@ New scans that only require a new way of calculating the positions can simply ov :icon: code-square :animate: fade-in-slide-down -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: FermatSpiralScan ``` @@ -70,7 +70,7 @@ Once all devices are staged and thus ready for the upcoming scan, a baseline rea It is sometimes necessary to perform additional operations before the core of the scan is executed. In BEC, these operations can be implemented in the `pre_scan` method: -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase.pre_scan ``` @@ -79,14 +79,14 @@ If the class attribute `pre_move` is set to `True`, the default `pre_scan` metho Now that all motors are ready and in position, we are finally ready to start the core of the scan. This is done by calling the `scan_core` method. Its default implementation is quite simple: -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase.scan_core ``` For each position in the scan, the method `_at_each_point` is called, providing the current index and a list of positions. The default implementation of `_at_each_point` performs the following actions: -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: ScanBase._at_each_point ``` @@ -135,7 +135,7 @@ The following example shows the configuration of the line scan: :icon: code-square :animate: fade-in-slide-down -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: LineScan ``` @@ -152,7 +152,7 @@ Both types of fly scans provide dedicated base classes that can and should be us :icon: code-square :animate: fade-in-slide-down -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: SyncFlyScanBase ``` @@ -164,7 +164,7 @@ Both types of fly scans provide dedicated base classes that can and should be us :icon: code-square :animate: fade-in-slide-down -```{literalinclude} ../../../bec_server/bec_server/scan_server/scans.py +```{literalinclude} ../../../../bec_server/bec_server/scan_server/scans.py :language: python :pyobject: AsyncFlyScanBase ``` diff --git a/docs/source/developer/user_interfaces/bec_gui.md b/docs/source/developer/user_interfaces/bec_gui.md index 2e7bd9e4..567329f7 100644 --- a/docs/source/developer/user_interfaces/bec_gui.md +++ b/docs/source/developer/user_interfaces/bec_gui.md @@ -1,5 +1,13 @@ (developer.bec_gui)= # GUI and Live Plotting -Coming soon... -In the meantime, have a look at the GUI documentation in the [user section](user.graphical_user_interface). \ No newline at end of file +```{figure} ../../assets/bec_widgets_glance.png +--- +width: 100% +name: bec_widgets_glance +alt: BEC Widgets at a glance +--- +``` + +Real-time plotting and data visualization play a crucial role in making sense of the data being collected. To facilitate this, BEC provides a live plotting interface through BEC Widgets. This toolkit takes advantage of BEC's architecture to offer advanced features and a seamless level of integration that surpasses what can be achieved with direct use of libraries such as matplotlib. BEC Widgets is designed to streamline the process of visualizing data in real-time, making it easier for users to interact with and interpret their data dynamically. Detailed documentation for both using and developing components within BEC Widgets is available [here](https://bec-widgets.readthedocs.io/en/latest/), offering guidance and insights to help users fully leverage the toolkit's capabilities. +