Move to markdown and cleanup how-to guides.

Author: TeresiaOlsson

docs/source/conf.py

@@ -14,11 +14,15 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+]
 
 templates_path = ['_templates']
 exclude_patterns = []
 
+source_suffix = ".md"
 
 
 # -- Options for HTML output -------------------------------------------------

docs/source/explanation/index.rst docs/source/explanation/index.mddocs/source/explanation/index.rst renamed to docs/source/explanation/index.md

@@ -1,4 +1,3 @@
-Explanations
-============
+# Explanations
 
 Welcome to the explanations section.

docs/source/how-to/apptainer.md

@@ -0,0 +1,55 @@
+# Installing Apptainer
+
+Virtual accelerators are deployed as [Apptainer](https://apptainer.org/) containers.
+
+Instructions for how to install and run Apptainer on different OS are available here.
+
+## Linux
+
+Installation instructions are available at <https://apptainer.org/docs/admin/main/installation.html#installation-on-linux>.
+
+Try to first install using the [pre-build packages](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages) for your Linux distribution.
+
+If that doesn't work (for example if it requires root permissions which you don't have), do an [unprivileged installation](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages) instead.
+
+You should then be able to run Apptainer in a terminal.
+
+## Windows
+
+For Windows you need to install and run in [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/). Follow the instructions at <https://apptainer.org/docs/admin/main/installation.html#windows>.
+
+You can then start the Ubuntu app which opens a Linux terminal where you can run Apptainer.
+
+## Mac
+
+For Mac you need to use Lima. Instructions are available at <https://apptainer.org/docs/admin/main/installation.html#mac> but more detailed instructions are below since some additonal steps are required.
+
+For ARM-based MacOS server:
+
+```
+brew install qemu lima
+
+limactl start –rosetta –vm-type=vz –network=vzNAT template://apptainer
+```
+
+For Intel-based MacOS server:
+
+```
+brew install lima
+
+limactl start –vm-type=vz –network=vzNAT template://apptainer
+```
+
+To run a container you need to first do the following command before you can run Apptainer:
+
+```
+limactl shell apptainer
+```
+
+To stop the container you need to do:
+
+```
+limactl stop apptainer
+
+limactl delete apptainer
+```

docs/source/how-to/contribute.md

@@ -0,0 +1,56 @@
+# Ways to Contribute
+
+Thank you for your interest in contributing to pyAML! This document outlines how you can help, whether you're fixing bugs, adding features, improving documentation, or participating in community discussions.
+
+## 1. Reporting Issues
+
+- **Bugs & Feature Requests:** Open an issue on GitHub. Use clear titles and provide as much detail as possible (steps to reproduce, expected/actual behaviour, screenshots, etc.).
+- Use an issue template if it is applicable to you. Don't forget to assign an issue to a project and set the status of the issue to TODO.
+- **Before Submitting:** Check existing issues to avoid duplicates.
+
+## 2. Working on Tasks
+
+- **Kanban Board:** We use [GitHub Projects](https://github.com/orgs/python-accelerator-middle-layer/projects) to manage tasks. Each column represents a stage in the workflow (e.g., "To Do", "In Progress", "Review", "Done").
+- **Claiming a Task:** Comment and assign yourself on the issue or card to let others know you’re working on it. Move the card to "In Progress".
+- **Part-time Contributors:** It’s okay to work at your own pace. Just keep the community updated on your progress.
+
+## 3. Submitting Changes
+
+- **Fork & Branch:** Fork the repo and create a branch for your changes.
+
+- **Commits:** Write clear, atomic commit messages. Reference the issue number if applicable.
+
+- **Formatting:** Ensure your code adheres to the project’s style guidelines. Run tests locally before submitting. It is recommended to use `pre-commit` hooks for this purpose.
+Sometimes pre-commit hook will block you committing due to formatting issues. They may be fixed automatically or require manual intervention. If they are fixed automatically just re-stage the files and commit again.
+If manual intervention is required, please follow the instructions provided by the pre-commit tool.
+
+- **Pull Requests (PRs):**
+  - Open a PR against the `main` branch.
+  - Include a description of your changes and reference the relevant issue.
+  - Ensure your code follows the project’s style and passes all tests.
+  - A maintainer will review your PR and may suggest changes.
+
+## 4. Documentation
+
+- **Improving Docs:** Fix typos, clarify instructions, or add missing documentation.
+- The documentation is located in <https://github.com/python-accelerator-middle-layer/documentation>. Submit a PR as you would for code changes.
+
+## 5. Participate in the Community
+
+- **Website:** Our project website is at [python-accelerator-middle-layer.github.io](https://python-accelerator-middle-layer.github.io/).
+There you can find information about upcoming meetings and how to join them.
+
+    ### Community Meetings
+    - **Schedule:** Once every few months.
+    - **Focus:** Discuss project direction, upcoming features, and community questions.
+
+    ### Maintainer Meetings
+    - **Schedule:** Bi-weekly, alternating with community meetings.
+    - **Focus:** Technical discussions, code reviews.
+
+    ## Getting Help
+    - **Questions?** Open a discussion on GitHub or ask in our [Matrix space](https://to.matrix.helmholtz.cloud/#/#pyaml:helmholtz.cloud).
+    - **Need Guidance?** Reach out to a maintainer or attend a maintainer or community meeting.
+
+## Recognition
+All contributions are valued and recognised. Significant contributions may be highlighted in release notes or on the project website.

docs/source/how-to/install.rst …/source/how-to/developer-installation.mddocs/source/how-to/install.rst renamed to docs/source/how-to/developer-installation.md docs/source/how-to/install.rst renamed to docs/source/how-to/developer-installation.md

@@ -1,43 +1,10 @@
-Installation
-==================
-
-## 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
+# 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.**
+```{important}
+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)
 
@@ -66,10 +33,10 @@ To do development work you need to clone the source code from GitHub and 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 use control system bindings you need to also install the packages for the bindings 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.
+    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 and is only intended for tests during development.

docs/source/how-to/index.md

@@ -0,0 +1,39 @@
+# How-to Guides
+
+Here you can find task-oriented guides organized by topic.
+
+```{toctree}
+:maxdepth: 1
+:caption: Getting Started
+
+python-basics
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Installation
+
+user-installation
+developer-installation
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Configuration
+
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Virtual Accelerator
+
+apptainer
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Contributing
+
+contribute
+release.md
+```

docs/source/how-to/index.rst

@@ -0,0 +1,95 @@
+# New to Python
+
+If you are a new Python user this page provides some help to get started. It also provides some advice for MATLAB users migrating to Python.
+
+Python is a large ecosystem with many tools to achieve similar things so this is not intended to be a complete list. Which tool to use is often based on personal preference and the intention of this guide is only to provide a starting point for you to find you preferred setup.
+
+## Integrated Development Environments
+
+Python can be run directly in a terminal or an [IPython](https://ipython.org/) shell but if you want to do more complex things like debug or develop code it is easier to use an Integrated Development Environment (IDE). There are many IDEs with Python support with different features, user experience etc so the choice is highly personal. Three common ones are:
+
+- **Spyder**:
+    <https://www.spyder-ide.org/>
+
+    Spyder is designed for scientific computing and data analysis. It has the most MATLAB-like interface which often makes it a preferred choice among MATLAB users. It works well when using standard scientific Python packages but has currently less support for custom Python classes. It also only has basic Git integration and works best with conda environments. There is an plugin for Jupyter notebooks but it is not available for all the installation options yet.
+
+- **VS Code**:
+    <https://code.visualstudio.com/>
+
+    VS Code supports Python through extensions. It also has extensions for other programming languages as well as for Jupyter notebooks. It has a very good Git integration making it a good choice if you are new to using version control and prefer to not use the terminal. It also has very good support for all type of virtual environments. In addition, it has extensions to connect to remote services (such as clusters) and JupyterHub. Many HPC centers therefore provide a web-based version for their users. It however makes heavy use of keyboard shortcuts which can be a bit of a learning curve for new users.
+
+- **PyCharm**:
+    <https://www.jetbrains.com/pycharm/>
+
+    PyCharm is a dedicated Python IDE. It has many features and customization possibilities and is often used by software professionals. There is both a community (free) and professional (paid) edition.
+
+If you are a new user getting started who doesn't know yet what you prefer, a good choice is likely to start with VS Code.
+
+##  Jupyter Notebooks
+
+A very common way to run Python in the scientific community is to use [Jupyter notebooks](https://jupyter.org/). Is a browser-based tool which is very useful for data visualisation and interactive work. It can be installed both in a basic version **Jupyter Notebook** or as **JupyterLab** which provides some useful IDE features. It is common that tutorials will be in the form of a notebook.
+
+## Installing Python
+
+There are many different ways to get an installation of Python. An important aspect is that you at some point might need to be able to switch between different versions and have more than one version installed simultaneously. There are different options available for this. Here are some common ones:
+
+- **pyenv**:
+    <https://github.com/pyenv/pyenv>
+
+    This is the most basic choice but probably too basic for most users. There is a plugin [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) if you also want the tool to manage virtual environments.
+
+- **conda**:
+    <https://docs.conda.io/projects/conda/en/stable/>
+
+    Conda is often used in the scientific community. There are several versions available and some might require a license. A good choice to avoid license issues is to choose [Miniforge](https://github.com/conda-forge/miniforge). This gives you a minimal installation of the free community edition. In addition to different Python versions, it also provides an easy way to manage and create virtual environments.
+
+- **uv**:
+    <https://docs.astral.sh/uv/>
+
+    Uv is a new tool which is intended as a single tool to replace the functionality of many other tools. In addition to managing Python versions and virtual environments it can also help to build packages. It however has a bit of a learning curve so is likely mostly a good choice for the experienced user who also wants to do development work.
+
+## Python Packages
+
+After you have installed Python you need to install packages for the code that you want to use. There are two common ways to do this:
+
+- **pip**:
+    <https://pip.pypa.io/en/stable/>
+
+    Pip is the standard package installer for Python. It is often automatically installed when you install Python and is easy to use. You can install from different sources as explained in the documentation [https://pip.pypa.io/en/stable/getting-started/](https://pip.pypa.io/en/stable/getting-started/).
+
+- **conda**
+
+    If you are using conda, it also provides its own way of installing packages. You can however still use pip in conda environments in case the package is not available as a conda package. The installation is similar to when using pip <https://www.anaconda.com/docs/getting-started/working-with-conda/packages/install-packages>.
+
+
+## Virtual Environments
+
+A key aspect of a good Python setup is to use virtual environments. A virtual environment is a self-contained directory which contains a Python installation for a specific version plus additional packages. The purpose is to install packages without fear of compatibility issues that might cause your entire Python setup to break. If something goes wrong, you can just delete the virtual environment and start over.
+
+```{warning}
+You should never install Python packages in your default Python environment. It can cause big problems and especially if your computer is using an OS which relies on Python.
+```
+
+The recommended workflow is to always create a virtual environment, activate it and then install the Python packages you need into it. There are two different versions of virtual environments:
+
+- **venv**:
+    <https://docs.python.org/3/library/venv.html>
+
+    This is the standard way that comes with the Python installation. It is very lightweight but can sometimes be annoying to use because you need to remember the command to activate the environment after it was created. The virtual environment is created in the current working folder so there is also no global way to manage your environments if you want an easy way to switch between environments. However, tools exist to extend the functionality such as [virtualenv](https://virtualenv.pypa.io/en/latest/) and [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/).
+
+- **conda**
+
+    Conda can also create virtual environments. It provides and easy way to activate and switch between environments so is a good choice for new users.
+
+Some IDEs has the functionality to help you create and switch between virtual environments. This works for both type of environments and can substantially simplify the workflow compared to using the terminal.
+
+## Example Resources
+
+There are many resources available for learning Python and also dedicated resources tailored for the scientific community. Several organisations provide free courses and material for scientists. Here are some recommendations:
+
+- **The Python documentation**: <https://www.python.org/>
+- **Python Packaging User Guide**: <https://packaging.python.org/en/latest/>
+- **Scientific Python**: <https://scientific-python.org/>
+- **Carpentries**: <https://carpentries.org/>
+- **CodeRefinery**: <https://coderefinery.org/>
+- **Software Sustainability Institute.**: <https://www.software.ac.uk/>

docs/source/how-to/python-basics.md

@@ -0,0 +1,7 @@
+# Release a new version on PyPI
+
+1. Create a branch for a release
+2. Provide a list of changes and release description in the merge request. Justify a version bump is necessary.
+3. Tag the corresponding version.
+4. Approve and merge the PR.
+5. CI/CD will take care of PyPi release. (Make sure the version in CI/CD deployment pipeline matches the one you just tagged.)

docs/source/how-to/release.md

@@ -0,0 +1,34 @@
+# User Installation
+
+The latest release can be installed from PyPI. If you want to communicate with a control system you also need to install the bindings you want by specifing extras.
+
+You need at least Python 3.11.
+
+```{note}
+Remember to always install in a virtual environment to avoid breaking your Python environment.
+```
+
+## Installing without Control System Bindings
+
+This if 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]
+```
+
+