From 76aab08c1ef9273f102a10999f3a44a9fc95b993 Mon Sep 17 00:00:00 2001 From: Benjamin Labrecque Date: Tue, 21 Jul 2026 17:01:54 +0200 Subject: [PATCH] docs: refactor and add entry points --- README.md | 88 ++---------------------------------- docs/developer/hosts.md | 19 ++++++++ docs/developer/overview.md | 3 ++ docs/user/add-new-service.md | 70 ++++++++++++++++++++++++++++ 4 files changed, 97 insertions(+), 83 deletions(-) create mode 100644 docs/developer/hosts.md create mode 100644 docs/developer/overview.md create mode 100644 docs/user/add-new-service.md diff --git a/README.md b/README.md index c1a70d3..b684968 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,12 @@ # SLS HLA Framework -## Getting started +## Documentation -Install [uv](https://docs.astral.sh/uv/) +### Users -## CLI +- [Add a new service](docs/user/add-new-service.md) -Using the CLI: +### Developers -``` -cd cli -uv sync -source .venv/bin/activate -agebd --help -``` +- [Overview](docs/developer/overview.md) -### Adding a new service - -``` -agebd service add --help -``` - -## Environments - -The services are deployed to 2 environments: - -| Environment | Network | Host | Deploy path on host | -|---|---|---|---| -|`prod` | `machine`| `sls-vserv-bd-hla01` | `/sls/bd/hla/prod/` | -| `dev` | `office` | `sls-vserv-bd-hla01-dev` | `/sls/bd/hla/dev/` | - - -### Process Variables (PVs) - -We distinguish between - -- `prod` vs `dev` PVs -- **services specific** PVs from a dedicated IOC vs **external** PVs from other IOCs - -#### PVs - Service Specific - -You create them, see (# TODO: docs...) - -`prod` and `dev` PVs automatically get created. - -In your code, you only use the `prod` name of a PV. The framework will automatically use the -`dev` name/PV when a service runs in the `dev` environment. - -#### PVs - External - -You can only access them. The framework will use the same PV in `prod` and `dev`, -i.e. there is no `dev` PV. - -#### PVs - Examples - -| Environment | Service Specific | External | -|---|---|---| -|`prod` | `PV("AGEBD-MYSERVICE:MYPVNAME")` | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` | -| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")` | - | - -### Python - -For python services there are 3 environments. The python environment is set through the env variable `AGEBD_ENV`. - -| Environment | PVs | -|---|---| -| `AGEBD_ENV=prod` | uses `prod` PVs | -| `AGEBD_ENV=dev` | uses `dev` PVs | -| `AGEBD_ENV=local` | uses fake/mock python objects as PVs, no access to real PVs | - -## Hosts overview - -Check which network a host lives in, e.g. for `sls-lca`: -```shell -ping sls-lca.psi.ch -``` - -### Machine Net (`prod`) - -- sls-lca -- sls-vserv-bd-01 -- sls-vserv-bd-hla01 - -### Office Net (`dev`) - -- sls-lc8 -- sls-lc9 -- sls-vserv-bd-01-dev -- sls-vserv-bd-hla01-dev diff --git a/docs/developer/hosts.md b/docs/developer/hosts.md new file mode 100644 index 0000000..d1d4cb5 --- /dev/null +++ b/docs/developer/hosts.md @@ -0,0 +1,19 @@ +# Hosts overview + +Check which network a host lives in, e.g. for `sls-lca`: +```shell +ping sls-lca.psi.ch +``` + +### Machine Net (`prod`) + +- sls-lca +- sls-vserv-bd-01 +- sls-vserv-bd-hla01 + +### Office Net (`dev`) + +- sls-lc8 +- sls-lc9 +- sls-vserv-bd-01-dev +- sls-vserv-bd-hla01-dev \ No newline at end of file diff --git a/docs/developer/overview.md b/docs/developer/overview.md new file mode 100644 index 0000000..c0fc363 --- /dev/null +++ b/docs/developer/overview.md @@ -0,0 +1,3 @@ +# HLA Framework BD + +TODO \ No newline at end of file diff --git a/docs/user/add-new-service.md b/docs/user/add-new-service.md new file mode 100644 index 0000000..5d31193 --- /dev/null +++ b/docs/user/add-new-service.md @@ -0,0 +1,70 @@ +# Adding a new service + +## Python setup + +Install the [uv](https://docs.astral.sh/uv/) package manager + +## CLI + +Using the CLI: + +``` +cd cli +uv sync +source .venv/bin/activate +agebd --help +``` + +### Adding a new service + +``` +agebd service add --help +``` + +## Environments + +The services are deployed to 2 environments: + +| Environment | Network | Host | Deploy path on host | +|---|---|---|---| +|`prod` | `machine`| `sls-vserv-bd-hla01` | `/sls/bd/hla/prod/` | +| `dev` | `office` | `sls-vserv-bd-hla01-dev` | `/sls/bd/hla/dev/` | + + +### Process Variables (PVs) + +We distinguish between + +- `prod` vs `dev` PVs +- **services specific** PVs from a dedicated IOC vs **external** PVs from other IOCs + +#### PVs - Service Specific + +You create them, see (# TODO: docs...) + +`prod` and `dev` PVs automatically get created. + +In your code, you only use the `prod` name of a PV. The framework will automatically use the +`dev` name/PV when a service runs in the `dev` environment. + +#### PVs - External + +You can only access them. The framework will use the same PV in `prod` and `dev`, +i.e. there is no `dev` PV. + +#### PVs - Examples + +| Environment | Service Specific | External | +|---|---|---| +|`prod` | `PV("AGEBD-MYSERVICE:MYPVNAME")` | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` | +| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")` | - | + +### Python + +For python services there are 3 environments. The python environment is set through the env variable `AGEBD_ENV`. + +| Environment | PVs | +|---|---| +| `AGEBD_ENV=prod` | uses `prod` PVs | +| `AGEBD_ENV=dev` | uses `dev` PVs | +| `AGEBD_ENV=local` | uses fake/mock python objects as PVs, no access to real PVs |