docs: improvements for the dev docs

docs/source/api_reference/api_reference.md

@@ -1,3 +1,4 @@
+(api_reference)=
 # API Reference
 
 ```{eval-rst}

docs/source/assets/portrait_48dp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="48px" viewBox="0 0 24 24" width="48px" fill="#000000"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M12 12c1.65 0 3-1.35 3-3s-1.35-3-3-3-3 1.35-3 3 1.35 3 3 3zm0-4c.55 0 1 .45 1 1s-.45 1-1 1-1-.45-1-1 .45-1 1-1zm6 8.58c0-2.5-3.97-3.58-6-3.58s-6 1.08-6 3.58V18h12v-1.42zM8.48 16c.74-.51 2.23-1 3.52-1s2.78.49 3.52 1H8.48zM19 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 16H5V5h14v14z"/></svg>

docs/source/assets/precision_manufacturing_48dp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 20 20" height="58px" viewBox="0 0 20 20" width="58px" fill="#000000"><g><rect fill="none" height="20" width="20" x="0"/></g><g><path d="M10.5,9C10.78,9,11,8.78,11,8.5V8.43l1.43,1.43c0.15,0.15,0.37,0.19,0.56,0.1l2.72-1.27c0.25-0.12,0.36-0.41,0.24-0.66v0 c-0.12-0.25-0.41-0.36-0.66-0.24l-2.4,1.12L11,7.01V6.99l1.89-1.89l2.4,1.12c0.25,0.12,0.55,0.01,0.66-0.24v0 c0.12-0.25,0.01-0.55-0.24-0.66l-2.72-1.27C12.8,3.96,12.58,4,12.43,4.15L11,5.57V5.5C11,5.22,10.78,5,10.5,5S10,5.22,10,5.5v1 H7.93c-0.26-1-1.27-1.71-2.4-1.45C4.8,5.22,4.21,5.82,4.05,6.54C3.83,7.56,4.37,8.47,5.21,8.84L6.5,14H6c-0.55,0-1,0.45-1,1v1h8v-1 c0-0.55-0.45-1-1-1h-1.14L7.56,8.23C7.73,8.02,7.86,7.77,7.93,7.5H10v1C10,8.78,10.22,9,10.5,9z M6,8C5.45,8,5,7.55,5,7 c0-0.55,0.45-1,1-1s1,0.45,1,1C7,7.55,6.55,8,6,8z M9.38,14H7.82L6.65,9.28h0.04L9.38,14z"/></g></svg>

docs/source/assets/rocket_launch_48dp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 20 20" height="48px" viewBox="0 0 20 20" width="48px" fill="#000000"><g><rect fill="none" height="20" width="20" x="0"/></g><g><g><path d="M14.45,10.86l0.26,2.1c0.06,0.46-0.1,0.92-0.43,1.25l-3.55,3.55l-1.41-4.24l-2.83-2.83L2.25,9.27l3.55-3.55 c0.33-0.33,0.79-0.49,1.25-0.43l2.1,0.26C13.92,0.78,17.8,2.2,17.8,2.2C17.8,2.2,19.22,6.08,14.45,10.86z M10.2,6.62 C9.18,7.64,8.37,9.06,7.9,9.97l2.12,2.12c0.91-0.46,2.34-1.27,3.36-2.3C16.18,7,16.54,4.67,16.5,3.5C15.33,3.46,13,3.82,10.2,6.62 z M14,7.5C14,6.68,13.32,6,12.5,6C11.67,6,11,6.68,11,7.5S11.67,9,12.5,9C13.32,9,14,8.33,14,7.5z M7.99,6.92L6.86,6.78L5.02,8.61 l1.62,0.54C6.97,8.52,7.43,7.71,7.99,6.92z M10.85,13.36l0.54,1.62l1.83-1.83l-0.14-1.14C12.29,12.57,11.48,13.03,10.85,13.36z M5.25,12.5c-0.62,0-1.18,0.25-1.59,0.66C2.44,14.38,2,18,2,18s3.62-0.44,4.84-1.66c0.41-0.41,0.66-0.97,0.66-1.59 C7.5,13.51,6.49,12.5,5.25,12.5z M5.78,15.28c-0.44,0.44-1.87,0.81-1.87,0.81s0.37-1.43,0.81-1.87c0.29-0.29,0.77-0.29,1.06,0 S6.07,14.99,5.78,15.28z"/></g></g></svg>

docs/source/assets/timeline_48dp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="48px" viewBox="0 0 24 24" width="48px" fill="#000000"><g><rect fill="none" height="24" width="24" x="0"/></g><g><g><path d="M23,8c0,1.1-0.9,2-2,2c-0.18,0-0.35-0.02-0.51-0.07l-3.56,3.55C16.98,13.64,17,13.82,17,14c0,1.1-0.9,2-2,2s-2-0.9-2-2 c0-0.18,0.02-0.36,0.07-0.52l-2.55-2.55C10.36,10.98,10.18,11,10,11c-0.18,0-0.36-0.02-0.52-0.07l-4.55,4.56 C4.98,15.65,5,15.82,5,16c0,1.1-0.9,2-2,2s-2-0.9-2-2s0.9-2,2-2c0.18,0,0.35,0.02,0.51,0.07l4.56-4.55C8.02,9.36,8,9.18,8,9 c0-1.1,0.9-2,2-2s2,0.9,2,2c0,0.18-0.02,0.36-0.07,0.52l2.55,2.55C14.64,12.02,14.82,12,15,12c0.18,0,0.36,0.02,0.52,0.07 l3.55-3.56C19.02,8.35,19,8.18,19,8c0-1.1,0.9-2,2-2S23,6.9,23,8z"/></g></g></svg>

docs/source/assets/toc_48dp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="48px" viewBox="0 0 24 24" width="48px" fill="#000000"><path d="M0 0h24v24H0V0zm0 0h24v24H0V0z" fill="none"/><path d="M3 9h14V7H3v2zm0 4h14v-2H3v2zm0 4h14v-2H3v2zm16 0h2v-2h-2v2zm0-10v2h2V7h-2zm0 6h2v-2h-2v2z"/></svg>

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.
+```
+````

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** \

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/

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

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.

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
 ```

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).
+```{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. 
+