From 9842a35c916347b14e87663afc5386aab94b9397 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 4 Sep 2026 14:28:29 +0200 Subject: [PATCH 1/4] Add substructure for how-to guides for better organisation. --- .../how-to/{ => contribute}/contribute.md | 0 .../source/how-to/{ => contribute}/release.md | 0 .../{ => getting-started}/python-basics.md | 0 docs/source/how-to/index.md | 25 +++++++++++++------ .../developer-installation.md | 0 .../{ => installation}/user-installation.md | 0 .../{ => virtual-accelerator}/apptainer.md | 0 7 files changed, 17 insertions(+), 8 deletions(-) rename docs/source/how-to/{ => contribute}/contribute.md (100%) rename docs/source/how-to/{ => contribute}/release.md (100%) rename docs/source/how-to/{ => getting-started}/python-basics.md (100%) rename docs/source/how-to/{ => installation}/developer-installation.md (100%) rename docs/source/how-to/{ => installation}/user-installation.md (100%) rename docs/source/how-to/{ => virtual-accelerator}/apptainer.md (100%) diff --git a/docs/source/how-to/contribute.md b/docs/source/how-to/contribute/contribute.md similarity index 100% rename from docs/source/how-to/contribute.md rename to docs/source/how-to/contribute/contribute.md diff --git a/docs/source/how-to/release.md b/docs/source/how-to/contribute/release.md similarity index 100% rename from docs/source/how-to/release.md rename to docs/source/how-to/contribute/release.md diff --git a/docs/source/how-to/python-basics.md b/docs/source/how-to/getting-started/python-basics.md similarity index 100% rename from docs/source/how-to/python-basics.md rename to docs/source/how-to/getting-started/python-basics.md diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md index 0b0aa22..9de2541 100644 --- a/docs/source/how-to/index.md +++ b/docs/source/how-to/index.md @@ -6,34 +6,43 @@ Here you can find task-oriented guides organized by topic. :maxdepth: 1 :caption: Getting Started -python-basics +getting-started/python-basics ``` ```{toctree} :maxdepth: 1 :caption: Installation -user-installation -developer-installation +installation/user-installation +installation/developer-installation ``` ```{toctree} :maxdepth: 1 :caption: Configuration +configuration/create-configuration + ``` ```{toctree} :maxdepth: 1 :caption: Virtual Accelerator -apptainer +virtual-accelerator/apptainer ``` ```{toctree} :maxdepth: 1 -:caption: Contributing +:caption: Validation + +validation/use-schema-registry +``` -contribute -release.md -``` \ No newline at end of file +```{toctree} +:maxdepth: 1 +:caption: Contribute + +contribute/contribute +contribute/release.md +``` diff --git a/docs/source/how-to/developer-installation.md b/docs/source/how-to/installation/developer-installation.md similarity index 100% rename from docs/source/how-to/developer-installation.md rename to docs/source/how-to/installation/developer-installation.md diff --git a/docs/source/how-to/user-installation.md b/docs/source/how-to/installation/user-installation.md similarity index 100% rename from docs/source/how-to/user-installation.md rename to docs/source/how-to/installation/user-installation.md diff --git a/docs/source/how-to/apptainer.md b/docs/source/how-to/virtual-accelerator/apptainer.md similarity index 100% rename from docs/source/how-to/apptainer.md rename to docs/source/how-to/virtual-accelerator/apptainer.md From 30492a54a7c981d9273318b516cacd5bfe391d51 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 4 Sep 2026 14:38:33 +0200 Subject: [PATCH 2/4] Updated index page for explanations. --- docs/source/explanation/index.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md index d8d9097..2fca463 100644 --- a/docs/source/explanation/index.md +++ b/docs/source/explanation/index.md @@ -1,3 +1,9 @@ # Explanations -Here you can find explanations of the concepts, design decisions, and underlying principles behind pyAML. \ No newline at end of file +Here you can find explanations of the concepts, design decisions, and underlying principles behind pyAML. + +```{toctree} +:maxdepth: 1 + +schema_and_validation +``` From 88f1114491441dbf021f2c21ed2eef8e0d1f4a4b Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 4 Sep 2026 14:39:27 +0200 Subject: [PATCH 3/4] Add explanation for validation concepts. --- .../explanation/schema_and_validation.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/source/explanation/schema_and_validation.md diff --git a/docs/source/explanation/schema_and_validation.md b/docs/source/explanation/schema_and_validation.md new file mode 100644 index 0000000..ec1d9c1 --- /dev/null +++ b/docs/source/explanation/schema_and_validation.md @@ -0,0 +1,44 @@ +# Configuration Schemas and Validation + +In pyAML, schemas are used to describe and validate the data for the configuration. The concept and ideas behind this are explained here. The architecture for the validation contains three components with distinct responsibilities: + +- `SchemaRegistry`: discover and store schemas +- `SchemaValidator`: validate configuration data +- `SchemaGenerator`: generate [JSON Schemas](https://json-schema.org/) + +## What Is a Schema and Why Use It? + +A schema describes the structure of data. This includes permitted fields, values and types. In pyAML, schemas are [Pydantic](https://docs.pydantic.dev/latest/) models which define which fields a configuration object may contain, the type of each field, and validation rules. + +This is implemented as a base class `ConfigurationSchema` which defines the minimum required fields for any item in the pyAML configuration. Other schema classes can inherit from this and extend with additional fields. + +Every configuration schema has a field `class_path` (with accepted alias `class`) containing the fully qualified class path of the object to construct, for example `mypackage.module.Class`. The configuration can in this way identify both the class and the data needed to create an object. + +In addition to this, the configuration schemas can be used to generate [JSON Schemas](https://json-schema.org/). JSON Schema is a common standard used by many tools, and this allows pyAML users to use already existing external tools for writing and validating the pyAML configuration. + +## Schema Registration + +The `SchemaRegistry` links Python classes to the schema that defines their valid configuration. It maps a fully qualified class path, such as `mypackage.module.Class`, to a `ConfigurationSchema` subclass describing the configuration schema of that class. + +For example: + +```text +my_package.devices.Magnet → MagnetConfigurationSchema +``` + +The registry is an in-memory catalog implemented as a singleton, meaning that creating a schema registry in different parts of pyAML returns the same registry. + +Every registered schema must inherit from `ConfigurationSchema` to ensure that the minimum required fields are defined for each item in the registry. + +Schemas can be registered manually or be automatically registered during import by using the `register_schema` decorator. It can generate a schema from the class or associate the class with +an explicitly defined schema. + +## Schema Validation + +The `SchemaValidator` uses the schema registry to find the schema for a specific class. It then validates the data using `Pydantic` and recursively processes nested configuration objects. + +## JSON Schema Generation + +JSON schemas can be generated using the `SchemaGenerator`. It uses the schema registry to generate JSON schema for the classes registered in the registry. The result can be used by tools such as editors, web interfaces, documentation tools etc which understand JSON schema. + +When a schema for a base class has registered schemas for subclasses, the generated schema includes those alternatives as a union. \ No newline at end of file From d3c6ed6341c279497eb9d266374d416c06922022 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Fri, 4 Sep 2026 14:40:04 +0200 Subject: [PATCH 4/4] Add start of how to for creating configuration. --- .../configuration/create-configuration.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/source/how-to/configuration/create-configuration.md diff --git a/docs/source/how-to/configuration/create-configuration.md b/docs/source/how-to/configuration/create-configuration.md new file mode 100644 index 0000000..8ec5a1d --- /dev/null +++ b/docs/source/how-to/configuration/create-configuration.md @@ -0,0 +1,27 @@ +# Create Configuration + +By creating a configuration it is possible to have pyAML create devices and applications automatically for several control modes. + +There are different ways to create a configuration and different formats are supported. +These are explained in this guide. + +## Principle + +The configuration is done on the level of an `Accelerator`. This allows not only to create devices and applications for different control modes but also to define parameters and metadata which are common for the accelerator. + +The syntax supports configuration of both pyAML classes and third party classes to allow the use of pyAML implementations as well as facility specific implementation in the same accelerator. This is done by for each item in the configuration define the field `class` or `class_path` to say which class to build an object of. + +## Format Options + +A configuration can be created and loaded using different formats: + +1. File + + The configuration can be written as a text file and loaded using `Accelerator.load()`. Both `YAML` and `JSON` are supported but `YAML` is considered the default option. + +2. Dictionary + + The configuration can be written as a nested dictionary and loaded using `Accelerator.from_dict()`. + + +To be continued with details about the different tools to help write it...