New installation instructions

README.md

@@ -1,53 +1,32 @@
 [![Documentation Status](https://readthedocs.org/projects/pyaml/badge/?version=latest)](https://pyaml.readthedocs.io/en/latest/?badge=latest)
 ![Current release](https://img.shields.io/github/v/tag/python-accelerator-middle-layer/pyaml)
 
-# pyAML: Python Accelerator Middle Layer
+# Python Accelerator Middle Layer
 
-Disclaimer: the pyAML software is still under development.
+Python Accelerator Middle Layer (pyAML) is a joint technology platform for design, commissioning and operation of particle accelerators.
 
-This repository is pyAML core. It is control system independent and provides the main functionality of pyAML (device abstraction for magnets, bpms, etc.; access to simulator (pyAT) and abstract implementation for control system). It is intended to be used together with a package that implements control system specific interface.
+The code is still under development. The features include among others:
 
-If you want to only tests for your machine and not develop, you shouldn't install this package. Instead go to the package for the bindings and install that one. It will install this package automatically.
+- A control system agnostic interface to interact with the accelerator.
+- Same interface to different backends: live accelerator, virtual accelerator and simulator.
+- Machine independence allowing configuration of different type of accelerators and facility specific naming conventions.
+- Unit conversions.
+- Automatic generation of metadata and standardized format for measurement data.
+- A set of standard applications and a framework for developing new applications.
+
+**This repository is for the core of pyAML.** It is control system independent and provides the core functionality of pyAML. It is intended to be used together with a package that implements the control system specific interface.
 
 Available packages for bindings:
 
 TANGO: [tango-pyaml](https://github.com/python-accelerator-middle-layer/tango-pyaml)
 TANGO or EPICS: [pyaml-cs-oa](https://github.com/python-accelerator-middle-layer/pyaml-cs-oa)
 
-#### Developer Installation
-
-1. Clone the repository. You need to also update the submodules.
-
-   ```
-   cd pyaml
-   git submodule update --init --recursive
-   ```
-2. Create a virtual environment and activate it
-3. Install the package in editable mode:
-
-   ```
-   pip install -e .
-   ```
-4. Install the development dependencies and pre-commit hooks
-
-   ```
-   pip install -e .[dev]
-   pre-commit install
-   ```
-
-5. If you want to try the examples using the control system bindings you also need to install those. See:
-
-   TANGO: [tango-pyaml](https://github.com/python-accelerator-middle-layer/tango-pyaml)
-   TANGO or EPICS: [pyaml-cs-oa](https://github.com/python-accelerator-middle-layer/pyaml-cs-oa)
-
-6. If you want to run tests manually using the TANGO bindings without requiring a live machine you can also install the the Dummy TANGO control system available in tests/dummy-cs/tango. It is a simple emulation that allows to check the interface to the control system. The implemented control system doesn't do anything but it is only intended for tests during the development.
+#### Installation
 
+Installation instructions for both user and development installation can be found in the [documentation](https://pyaml.readthedocs.io/en/latest/?badge=latest).
 
 #### Documentation
 
-The documentation is hosted on Read the Docs: [pyaml](https://pyaml.readthedocs.io/en/latest/?badge=latest).
-
-#### Examples
+The documentation is available [here](https://pyaml.readthedocs.io/en/latest/?badge=latest).
 
-Examples are available in the `examples` folder of the repository.
-Additionally, in the documentation there are example Jupyter notebooks available.
+In the documentation there are both examples and Jupyter notebooks available for how to use the package.

docs/getting-started/installation.md

@@ -1,4 +1,75 @@
 Installation
-======
+==================
 
-To write...
+## User Installation
+
+The latest release can be installed from PyPI. If you want to communicate with a control system you in addition need to install the bindings you want by specifing extras.
+
+You need at least Python 3.11.
+
+**Remember to always install in a virtual environment to avoid breaking your Python environment.**
+
+### Installing without Control System Bindings
+
+
+For example if you just want to use the simulator.
+
+```
+pip install accelerator-middle-layer
+```
+
+
+### Installing with Control System Bindings
+
+Available options for installing with control system bindings are:
+
+- `tango-pyaml` for the tango-pyaml bindings.
+-  `cs-oa-epics` for `ophyd-async` bindings with both EPICS channel and PV access.
+-  `cs-oa-tango` for `ophyd-async` bindings for TANGO.
+
+Example usage:
+
+```
+pip install accelerator-middle-layer[cs-oa-epics] 
+```
+
+## Developer Installation
+
+To do development work you need to clone the source code from GitHub and install in editable mode.
+
+**Note: if you are not a maintainer of the code and have write permissions to the repository you need to first fork the repository.**
+
+1. Clone the repository (or your fork)
+
+    The repository uses submodules so they also need to be initialized. This can be done in the same step by including ``--recurse-submodules``.
+
+    Example usage:
+
+    ```
+    git clone --recurse-submodules https://github.com/python-accelerator-middle-layer/pyaml.git
+    ```
+
+2. Make a virtual environment and activate it. It needs to use >= Python 3.11.
+
+3. Install the code in editable mode including development dependencies.
+
+    ```
+    cd pyaml
+    pip install -e .[dev]
+    ```
+
+4. Install the pre-commit hooks.
+
+    ```
+    pre-commit install
+    ```
+
+5. Install control system bindings *(optional)*
+
+    If you want to use control system bindings you need to also install the package for the binding you want to use. Follow the installation instructions in the corresponding repository.
+
+    If you want to do development work on the bindings they need to be installed in editable mode, but if not you can install the latest release from PyPI.
+
+6. Install dummy control system for TANGO *(optional)*
+
+    If you want to test the TANGO bindings without requiring a live machine or virtual accelerator you can install the dummy TANGO control system available in `tests/dummy-cs/tango`. It is a simple emulation that allows to check the interface to the control system. The control system doesn't do anything but is only intended for tests during development.

pyproject.toml

@@ -15,6 +15,9 @@ exclude = [
 [tool.hatch.build.targets.wheel]
 packages = ["pyaml"]
 
+[tool.hatch.metadata]
+allow-direct-references = true
+
 [project]
 name = "accelerator-middle-layer"
 description = "Python Accelerator Middle Layer"
@@ -50,6 +53,19 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+
+tango-pyaml = [
+    "tango-pyaml",
+]
+
+cs-oa-epics = [
+    "pyaml-cs-oa[epics]",
+]
+
+cs-oa-tango = [
+    "pyaml-cs-oa[tango]",
+]
+
 test = [
     "pytest>=7.4",
     "pytest-cov>=3.0",