From af995a74f34d59eeaff5d9100117f103ec79765d Mon Sep 17 00:00:00 2001 From: wyzula-jan <133381102+wyzula-jan@users.noreply.github.com> Date: Tue, 12 Dec 2023 11:23:55 +0100 Subject: [PATCH] docs: readdocs updated --- docs/developer/developer.md | 16 ++++++++++- docs/index.md | 12 ++++---- docs/introduction/introduction.md | 16 +++++++++++ docs/user/apps.md | 39 ++++++++++++++++++++++++++ docs/user/apps/modular_app.md | 6 ++++ docs/user/apps/motor_app.md | 4 +++ docs/user/apps/plot_app.md | 6 ++++ docs/user/customisation.md | 13 +++++++++ docs/user/installation.md | 46 +++++++++++++++++++++++++++++++ docs/user/user.md | 35 +++++++++++++++++++++++ docs/user/widgets.md | 6 ++++ 11 files changed, 193 insertions(+), 6 deletions(-) create mode 100644 docs/user/apps.md create mode 100644 docs/user/apps/modular_app.md create mode 100644 docs/user/apps/motor_app.md create mode 100644 docs/user/apps/plot_app.md create mode 100644 docs/user/customisation.md create mode 100644 docs/user/installation.md create mode 100644 docs/user/widgets.md diff --git a/docs/developer/developer.md b/docs/developer/developer.md index df74fa06..924b35a2 100644 --- a/docs/developer/developer.md +++ b/docs/developer/developer.md @@ -1,2 +1,16 @@ (developer)= -# Developer \ No newline at end of file +# Development + +To contribute to the development of BEC Widgets, start by setting up the development environment: + +1. **Clone the Repository**: +```bash +git clone https://gitlab.psi.ch/bec/bec-widgets +cd bec-widgets +``` +2. **Install in Editable Mode**: + +Installing the package in editable mode allows you to make changes to the code and test them in real-time. +```bash +pip install -e .[dev] +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index c1b4900d..d2f2b9fe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,29 +9,31 @@ :link: introduction :link-type: ref -General information about BEC Widgets. +General information. ``` ```{grid-item-card} User :link: user :link-type: ref -Information for users of BEC Widgets. +Information for users. ``` ```{grid-item-card} Developer :link: developer :link-type: ref -Information for developers of BEC Widgets. +Information for developers. ``` ```` ```{toctree} -:maxdepth: 2 +--- +numbered: true +maxdepth: 1 +--- introduction/introduction user/user developer/developer -``` diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md index d3d2a96e..bdcdf678 100644 --- a/docs/introduction/introduction.md +++ b/docs/introduction/introduction.md @@ -1,2 +1,18 @@ (introduction)= # Introduction + +## Overview + +BEC Widgets is a GUI framework developed with beamline scientists in mind, aiming to provide a modern and modular environment for interacting with experiments. This package offers a suite of widgets specifically designed to enhance the workflow of beamline experiments, including features for running scans and data visualization. + +Targeting the unique needs of beamline scientists, BEC Widgets stands out with its modular approach to widget design and high customizability. This flexibility allows for tailored solutions that meet the specific requirements of each beamline. + +**Key Features**: + +- **Integration:** Seamlessly integrates with [BEC (Beamline Experiment Control)](https://gitlab.psi.ch/bec/bec), ensuring a cohesive and efficient experiment control experience. +- **Support for PyQt5 and PyQt6:** Provides compatibility with both PyQt5 and PyQt6, offering versatility in your development environment. +- **Widget Modularity:** Features modular widgets that can be easily combined to create customized applications, perfectly aligning with the diverse needs of beamline experiments. + +## Getting Started + +For detailed usage instructions and examples showcasing the practical applications of BEC Widgets, please refer to the [User](#user) section. Developers interested in contributing or customizing BEC Widgets can find more information in the [Developer](#developer) section. \ No newline at end of file diff --git a/docs/user/apps.md b/docs/user/apps.md new file mode 100644 index 00000000..42005a9b --- /dev/null +++ b/docs/user/apps.md @@ -0,0 +1,39 @@ +(user.apps)= +# Applications + +In the `bec_widgets/examples` directory, you will find practical applications that demonstrate the capabilities of BEC Widgets in real-world scenarios. These applications showcase the adaptability and functionality of the framework for various beamline experiment needs. + +**Motor Alignment Tool** + +This tool assists in aligning motors with samples during experiments. It enables users to move motors, visually track their movement, and record positions for precise alignment. + +- **Location:** `bec_widgets/examples/motor_movement` +- **Further Details:** [Motor Alignment Tool Documentation](#user.apps.motor_app) + +**General Plotting Live Acquisition Tool** + +This application is designed for live data visualization. It allows users to view real-time signals from detectors in a multi-grid layout, facilitating immediate analysis during experiments. + +- **Location:** `bec_widgets/examples/plot_app` +- **Further Details:** [General Plotting Live Acquisition Tool Documentation](#user.apps.plot_app) + + +**Modular Application** + +A bespoke application built entirely using BEC Widgets' modular components. This example illustrates the framework's flexibility in creating customized GUIs tailored to specific experimental setups. + +- **Location:** `bec_widgets/examples/modular_app` +- **Further Details:** [Modular Application](#user.apps.modular_app) + +--- +Note: The documentation for these applications is currently under development. The provided links will direct you to their respective pages once the documentation is complete. + +```{toctree} +--- +maxdepth: 1 +hidden: true +--- + +apps/motor_app +apps/plot_app +apps/modular_app diff --git a/docs/user/apps/modular_app.md b/docs/user/apps/modular_app.md new file mode 100644 index 00000000..e844deaa --- /dev/null +++ b/docs/user/apps/modular_app.md @@ -0,0 +1,6 @@ +(user.apps.modular_app)= + +# Modular Application + + +_to be added..._ diff --git a/docs/user/apps/motor_app.md b/docs/user/apps/motor_app.md new file mode 100644 index 00000000..9677465e --- /dev/null +++ b/docs/user/apps/motor_app.md @@ -0,0 +1,4 @@ +(user.apps.motor_app)= +# Motor Alignment + +_to be added..._ diff --git a/docs/user/apps/plot_app.md b/docs/user/apps/plot_app.md new file mode 100644 index 00000000..4ea3b8ce --- /dev/null +++ b/docs/user/apps/plot_app.md @@ -0,0 +1,6 @@ +(user.apps.plot_app)= + +# General Plotting Tool + + +_to be added..._ \ No newline at end of file diff --git a/docs/user/customisation.md b/docs/user/customisation.md new file mode 100644 index 00000000..e50fb00c --- /dev/null +++ b/docs/user/customisation.md @@ -0,0 +1,13 @@ +(user.customisation)= +# Customisation + +BEC Widgets are designed to be used with QtDesigner to quicly design GUI. + + +## Example of promoting widgets in Qt Designer + +_Work in progress_ + +## Implementation of plugins into Qt Designer + +_Work in progress_ diff --git a/docs/user/installation.md b/docs/user/installation.md new file mode 100644 index 00000000..5e1d1d65 --- /dev/null +++ b/docs/user/installation.md @@ -0,0 +1,46 @@ +(user.installation)= +# Installation + + +**Prerequisites** + +Before installing BEC Widgets, please ensure the following requirements are met: + +1. **Python Version:** BEC Widgets requires Python version 3.9 or higher. Verify your Python version to ensure compatibility. +2. **BEC Installation:** BEC Widgets works in conjunction with BEC. While BEC is a dependency and will be installed automatically, you can find more information about BEC and its installation process in the [BEC documentation](https://beamline-experiment-control.readthedocs.io/en/latest/). + +**Standard Installation** + +Install BEC Widgets using the pip package manager. Open your terminal and execute: + +```bash +pip install bec-widgets +``` + +This command installs BEC Widgets along with its dependencies, including the default PyQt6. + +**Selecting a PyQt Version** + +BEC Widgets supports both PyQt5 and PyQt6. To install a specific version, use: + +For PyQt6: + +```bash +pip install bec-widgets[pyqt6] +``` + +For PyQt5: + +```bash +pip install bec-widgets[pyqt5] +``` + +**Troubleshooting** + +If you encounter issues during installation, particularly with PyQt, try purging the pip cache: + +```bash +pip cache purge +``` + +This can resolve conflicts or issues with package installations. \ No newline at end of file diff --git a/docs/user/user.md b/docs/user/user.md index c556f9fd..3102f2a5 100644 --- a/docs/user/user.md +++ b/docs/user/user.md @@ -1,3 +1,38 @@ (user)= # User +**Overview** + +Welcome to the User section of the BEC Widgets documentation! BEC Widgets is a versatile GUI framework tailored for beamline scientists, enabling efficient and intuitive interaction with beamline experiments. This section is designed to guide both new and experienced users through the essential aspects of utilizing BEC Widgets. + +**Key Topics** + +- [Installing BEC Widgets](#user.installation): Instructions for installing BEC Widgets on your system. + +- [Example Applications](#user.apps): Overview of bespoke applications and demonstrations of BEC Widgets in action, showcasing its use in real-world beamline scenarios. + +- [Widgets Overview](#user.widgets): Detailed information on the variety of widgets available, their functions, and how to use them effectively. + +- [Customization and Configuration](#user.customisation): Tips on customizing and configuring BEC Widgets to suit your specific experimental needs using Qt Designer. + +**Bug Reports and Feature Requests** + +We value your feedback and contributions to improving BEC Widgets. If you encounter any issues or have ideas for new features, we encourage you to report them. + +- **Bug Reports:** If you find a bug or an issue, please report it on our repository's [Issues page](https://gitlab.psi.ch/bec/bec-widgets/-/issues?sort=created_date&state=opened). We have a template for bug reporting to help you provide all necessary information. +- **Feature Requests:** Have an idea for a new feature or an enhancement? Share it with us on the [Issues page](https://gitlab.psi.ch/bec/bec-widgets/-/issues?sort=created_date&state=opened) of our repository. We have a feature request template that you can use to describe your proposal. + +**Development** + +For advanced details about BEC Widgets’ internal architecture, development contributions, or customization techniques, please explore the [Developer](#developer) section. + +```{toctree} +--- +maxdepth: 3 +hidden: true +--- + +installation +apps +widgets +customisation \ No newline at end of file diff --git a/docs/user/widgets.md b/docs/user/widgets.md new file mode 100644 index 00000000..ecbaf88a --- /dev/null +++ b/docs/user/widgets.md @@ -0,0 +1,6 @@ +(user.widgets)= +# Widgets + +Guide to use widgets. + +_work in progress_ \ No newline at end of file