Skip to content

Tweaks to the explanation of the catalog #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GamelinAl merged 3 commits into from
Sep 25, 2026
Merged

Tweaks to the explanation of the catalog #47

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
79efc5d
Added a tip to highlight that using the dynamic catalog is the recomm…
TeresiaOlsson Sep 24, 2026
8a31ec6
List classes for static catalog in tango-pyaml as a list.
TeresiaOlsson Sep 24, 2026
9d1b0bb
Updated info and config examples for the dynamic catalog.
TeresiaOlsson Sep 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/source/explanation/catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,33 +16,34 @@ The catalog makes it possible to use simple keys in the pyAML configuration and

## Dynamic Catalog

```{tip}
The dynamic catalog does not require a configuration file and it is therefore the recommended option for most use cases.
```

In this version, the configuration is extracted from a dynamic source. This can be directly from the control system or some other source, for example a database, depending on the chosen backend and its catalog implementation.

This requires access to the source, for example by being on the same network, but no configuration file for the control system configuration has to be loaded by pyAML.

Example of configuration for dynamic catalog:
Example of configuration for dynamic catalog for the `pyaml-cs-oa` bindings :

```yaml
controls:
- class: pyaml_cs_oa.controlsystem.OphydAsyncControlSystem
name: live
catalog:
class: pyaml_cs_oa.dynamic_catalog.DynamicCatalog
backend: tango
backend: tango
```

With `pyaml-cs-oa`, a dynamic catalog is also used when no catalog is given, based on the `backend` field of the control system:
The backend (currently TANGO or EPICS) is specified using the `backend` field.

For the `tango-pyaml` bindings no backend needs to be specified:

```yaml
controls:
- class: pyaml_cs_oa.controlsystem.OphydAsyncControlSystem
- class: tango.pyaml.tango_catalog.TangoCatalog
name: live
backend: tango
```

Dynamic catalogs are currently provided by `pyaml-cs-oa`. Check the documentation of your control-system bindings for the catalogs they support.
Check the [API documentation](../reference/index.md) for all the options for the bindings you want to use.

## Static Catalog

Expand All @@ -59,7 +60,7 @@ controls:
catalog: fodo_1gev_6d_pyaml_catalogs-oa.yaml
```

Example of a static catalog file for `pyaml-cs-oa`, with one entry:
Example of a static catalog file for `pyaml-cs-oa` with a single entry:

```yaml
class: pyaml_cs_oa.static_catalog.StaticCatalog
Expand All @@ -72,6 +73,9 @@ entries:
unit: 1/m
```

The same catalog for `tango-pyaml` uses the classes of that package (`tango.pyaml.static_catalog.StaticCatalog`, `tango.pyaml.static_catalog_entry.StaticCatalogEntry` and `tango.pyaml.attribute.Attribute`).
The static catalog for `tango-pyaml` uses the corresponding classes for that package:
- `tango.pyaml.static_catalog.StaticCatalog`
- `tango.pyaml.static_catalog_entry.StaticCatalogEntry`
- `tango.pyaml.attribute.Attribute`

This format follows the same syntax as for the rest of the pyAML configuration since during the loading process the file is read and the content added to the rest of the pyAML configuration.
Loading