From 6ba5193e9ec71ad1df871eef44a4aba4781a04c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Mon, 19 May 2025 14:38:08 +0200 Subject: [PATCH 1/3] docs: remove commented-out information --- docs/user-guide/interaction/README.md | 63 --------------------------- 1 file changed, 63 deletions(-) diff --git a/docs/user-guide/interaction/README.md b/docs/user-guide/interaction/README.md index 8c6b19b..e363cde 100644 --- a/docs/user-guide/interaction/README.md +++ b/docs/user-guide/interaction/README.md @@ -16,66 +16,3 @@ include-markdown "./Python Client.md" heading-offset=1 %} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From b9cec19b0227e4fcad92c542a5ce9c12ed890bd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Mon, 19 May 2025 14:25:49 +0200 Subject: [PATCH 2/3] docs: updating and adding links --- docs/user-guide/Configuration.md | 28 +++++++++---------- .../interaction/Auto-generated Frontend.md | 2 +- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/Configuration.md b/docs/user-guide/Configuration.md index efebb22..d65e0ae 100644 --- a/docs/user-guide/Configuration.md +++ b/docs/user-guide/Configuration.md @@ -30,7 +30,7 @@ example of how to separate service code from configuration. - **`ENVIRONMENT`**: Defines the operation mode (`"development"` or `"production"`), which influences - behaviour such as logging (see [Logging in pydase](https://github.com/tiqi-group/pydase?tab=readme-ov-file#logging-in-pydase)). + behaviour such as logging (see [Logging in pydase](./Logging.md)). - **`SERVICE_CONFIG_DIR`**: Specifies the directory for configuration files (e.g., `web_settings.json`). Defaults @@ -46,7 +46,7 @@ example of how to separate service code from configuration. port. Default: `8001`. - **`GENERATE_WEB_SETTINGS`**: - When `true`, generates or updates the `web_settings.json` file. Existing entries are + When `true`, generates or updates the `web_settings.json` file (see [Tailoring Frontend Component Layout](../interaction/#tailoring-frontend-component-layout)). Existing entries are preserved, and new entries are appended. ### Configuring `pydase` via Keyword Arguments @@ -70,32 +70,32 @@ server = Server( ## Separating Service Code from Configuration -To decouple configuration from code, `pydase` utilizes `confz` for configuration -management. Below is an example that demonstrates how to configure a `pydase` service +To decouple configuration from code, `pydase` utilizes `confz` for configuration +management. Below is an example that demonstrates how to configure a `pydase` service for a sensor readout application. ### Scenario: Configuring a Sensor Service -Imagine you have multiple sensors distributed across your lab. You need to configure +Imagine you have multiple sensors distributed across your lab. You need to configure each service instance with: 1. **Hostname**: The hostname or IP address of the sensor. 2. **Authentication Token**: A token or credentials to authenticate with the sensor. -3. **Readout Interval**: A periodic interval to read sensor data and log it to a +3. **Readout Interval**: A periodic interval to read sensor data and log it to a database. Given the repository structure: ```bash title="Service Repository Structure" my_sensor -├── pyproject.toml -├── README.md -└── src - └── my_sensor +├── pyproject.toml +├── README.md +└── src + └── my_sensor ├── my_sensor.py - ├── config.py - ├── __init__.py - └── __main__.py + ├── config.py + ├── __init__.py + └── __main__.py ``` Your service might look like this: @@ -119,7 +119,7 @@ class MySensorConfig(confz.BaseConfig): This class defines configurable parameters and loads values from a `config.yaml` file located in the service’s configuration directory (which is configurable through an -environment variable, see [above](#configuring-pydase-using-environment-variables)). +environment variable, see [above](#configuring-pydase-using-environment-variables)). A sample YAML file might look like this: ```yaml title="config.yaml" diff --git a/docs/user-guide/interaction/Auto-generated Frontend.md b/docs/user-guide/interaction/Auto-generated Frontend.md index 5b79fe6..77685da 100644 --- a/docs/user-guide/interaction/Auto-generated Frontend.md +++ b/docs/user-guide/interaction/Auto-generated Frontend.md @@ -89,7 +89,7 @@ Each key in the file corresponds to the full access path of public attributes, p - **Control Component Visibility**: Utilize the `"display"` key-value pair to control whether a component is rendered in the frontend. Set the value to `true` to make the component visible or `false` to hide it. - **Adjustable Component Order**: The `"displayOrder"` values determine the order of components. Alter these values to rearrange the components as desired. The value defaults to [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER). -The `web_settings.json` file will be stored in the directory specified by the `SERVICE_CONFIG_DIR` environment variable. You can generate a `web_settings.json` file by setting the `GENERATE_WEB_SETTINGS` to `True`. For more information, see the [configuration section](../Configuration). +The `web_settings.json` file will be stored in the directory specified by the `SERVICE_CONFIG_DIR` environment variable. You can generate a `web_settings.json` file by setting the `GENERATE_WEB_SETTINGS` to `True`. For more information, see the [configuration section](../Configuration.md). For example, styling the following service From 2c1db3fa45c09a5ae220115bc9ac4a2b1948415d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Mon, 19 May 2025 15:01:35 +0200 Subject: [PATCH 3/3] docs: restructuring Interaction section in User Guide --- docs/getting-started.md | 4 ++-- docs/index.md | 2 +- docs/user-guide/Configuration.md | 4 ++-- ...Frontend.md => Auto-generated-Frontend.md} | 0 .../{Python Client.md => Python-Client.md} | 0 docs/user-guide/interaction/README.md | 19 ++++--------------- .../{RESTful API.md => RESTful-API.md} | 0 7 files changed, 9 insertions(+), 20 deletions(-) rename docs/user-guide/interaction/{Auto-generated Frontend.md => Auto-generated-Frontend.md} (100%) rename docs/user-guide/interaction/{Python Client.md => Python-Client.md} (100%) rename docs/user-guide/interaction/{RESTful API.md => RESTful-API.md} (100%) diff --git a/docs/getting-started.md b/docs/getting-started.md index e5b6bf0..2e62652 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,7 +5,7 @@ end="" %} -[RESTful API]: ./user-guide/interaction/README.md#restful-api -[Python RPC Client]: ./user-guide/interaction/README.md#python-rpc-client +[RESTful API]: ./user-guide/interaction/RESTful-API.md +[Python RPC Client]: ./user-guide/interaction/Python-Client.md [Custom Components]: ./user-guide/Components.md#custom-components-pydasecomponents [Components]: ./user-guide/Components.md diff --git a/docs/index.md b/docs/index.md index c198f93..949ae63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ [Defining DataService]: ./getting-started.md#defining-a-dataservice [Web Interface Access]: ./getting-started.md#accessing-the-web-interface [Short RPC Client]: ./getting-started.md#connecting-to-the-service-via-python-rpc-client -[Customizing Web Interface]: ./user-guide/interaction/README.md#customization-options +[Customizing Web Interface]: ./user-guide/interaction/Auto-generated-Frontend.md#customization-options [Task Management]: ./user-guide/Tasks.md [Units]: ./user-guide/Understanding-Units.md [Property Validation]: ./user-guide/Validating-Property-Setters.md diff --git a/docs/user-guide/Configuration.md b/docs/user-guide/Configuration.md index d65e0ae..19928b5 100644 --- a/docs/user-guide/Configuration.md +++ b/docs/user-guide/Configuration.md @@ -46,8 +46,8 @@ example of how to separate service code from configuration. port. Default: `8001`. - **`GENERATE_WEB_SETTINGS`**: - When `true`, generates or updates the `web_settings.json` file (see [Tailoring Frontend Component Layout](../interaction/#tailoring-frontend-component-layout)). Existing entries are - preserved, and new entries are appended. + When `true`, generates or updates the `web_settings.json` file (see [Tailoring Frontend Component Layout](./interaction/Auto-generated-Frontend.md#tailoring-frontend-component-layout)). + Existing entries are preserved, and new entries are appended. ### Configuring `pydase` via Keyword Arguments diff --git a/docs/user-guide/interaction/Auto-generated Frontend.md b/docs/user-guide/interaction/Auto-generated-Frontend.md similarity index 100% rename from docs/user-guide/interaction/Auto-generated Frontend.md rename to docs/user-guide/interaction/Auto-generated-Frontend.md diff --git a/docs/user-guide/interaction/Python Client.md b/docs/user-guide/interaction/Python-Client.md similarity index 100% rename from docs/user-guide/interaction/Python Client.md rename to docs/user-guide/interaction/Python-Client.md diff --git a/docs/user-guide/interaction/README.md b/docs/user-guide/interaction/README.md index e363cde..22b6b5a 100644 --- a/docs/user-guide/interaction/README.md +++ b/docs/user-guide/interaction/README.md @@ -1,18 +1,7 @@ # Interacting with `pydase` Services -`pydase` offers multiple ways for users to interact with the services they create, providing flexibility and convenience for different use cases. This section outlines the primary interaction methods available, including an auto-generated frontend, a RESTful API, and a Python client based on Socket.IO. +`pydase` offers multiple ways for users to interact with the services they create. -{% - include-markdown "./Auto-generated Frontend.md" - heading-offset=1 -%} - -{% - include-markdown "./RESTful API.md" - heading-offset=1 -%} - -{% - include-markdown "./Python Client.md" - heading-offset=1 -%} +- [Auto-generated Frontend](./Auto-generated-Frontend.md) +- [RESTful API](./RESTful-API.md) +- [Python Client](./Python-Client.md) diff --git a/docs/user-guide/interaction/RESTful API.md b/docs/user-guide/interaction/RESTful-API.md similarity index 100% rename from docs/user-guide/interaction/RESTful API.md rename to docs/user-guide/interaction/RESTful-API.md