Merge branch 'doc/convert_README_from_rst_to_MD' into 'master'

doc[README][RTD]: Refactor README from RST to MarkDown and add jupyter usage installation instructions.

See merge request !1048

docs/development/installation.md

@@ -11,48 +11,75 @@ to do this.
 
 ## Installation using python virtual environment - recommended
 
-`pycalibration` uses the same version of Python as Karabo, which in June 2021
-updated to use Python 3.11. Currently the default python installation on Maxwell
+`pycalibration` uses Python 3.11. Currently the default python installation on Maxwell
 is still Python 3.9, so Python 3.11 needs to be loaded from a different
 location.
 
-Therefore `pyenv` is used, we provide a pyenv installation at
-`/gpfs/exfel/sw/calsoft/.pyenv` which we use to manage different versions of
-python. This can be activated with ``source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate``
+We use `pyenv` to manage different Python versions. A pyenv installation is provided at
+`/gpfs/exfel/sw/calsoft/.pyenv`.
 
-A quick setup would be:
-
-1.  `source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate`
-2.  `git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git && cd pycalibration` -
-    clone the offline calibration package from EuXFEL GitLab
-3.  `pyenv shell 3.11.9` - load required version of python
-4.  `python3 -m venv .venv` - create the virtual environment
-5.  `source .venv/bin/activate` - activate the virtual environment
-6.  `python3 -m pip install --upgrade pip` - upgrade version of pip
-7.  `python3 -m pip install .` - install the pycalibration package (add
-    `-e` flag for editable development installation)
-
-Copy/paste script:
+To install pycalibration, follow these steps:
 
 ```bash
+# Activate pyenv
 source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate
+
+# Clone the repository
 git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git
 cd pycalibration
+
+# Set up Python environment
 pyenv shell 3.11.9
 python3 -m venv .venv
 source .venv/bin/activate
+
+# Install pycalibration
 python3 -m pip install --upgrade pip
-python3 -m pip install .  # `-e` flag for editable install, e.g. `pip install -e .`
+# Use 'pip install -e .' for editable install
+python3 -m pip install .
 ```
 
+## Working with Jupyter Notebooks
+
+If you plan to work with Jupyter notebooks interactively, you have two main options:
+
+### Option 1: Install Jupyter Notebook locally
+
+if you prefer to run Jupyter notebooks on your local machine or on Maxwell, you can install the `notebook` package in your virtual environment:
+
+```bash
+python3 -m pip install notebook==6.2.0
+```
+
+After installation, you can start a Jupyter notebook server by running:
+
+```bash
+jupyter notebook
+```
+
+### Option 2: Use max-jhub (Recommended)
+
+Alternatively, we recommend using max-jhub, a JupyterHub instance available at DESY.
+This option provides a convenient web-based environment for running Jupyter notebooks without needing to set up everything locally.
+
+For detailed instructions on how to use max-jhub, please refer to these documentations:
+
+- [Max-jhub DESY Documentation](https://confluence.desy.de/display/MXW/JupyterHub+on+Maxwell)
+- [Max-jhub EuXFEL User Documentation](https://rtd.xfel.eu/docs/data-analysis-user-documentation/en/latest/jhub/#via-max-jhub-recommended)
+
+To use max-jhub effectively with pycalibration, make sure you've created an ipython kernel as
+described in the [Creating an ipython kernel for virtual environments](#creating-an-ipython-kernel-for-virtual-environments) section below.
+
 ## Creating an ipython kernel for virtual environments
 
 To create an ipython kernel with pycalibration available you should (if
 using a venv) activate the virtual environment first, and then run:
 
 ```bash
-python3 -m pip install ipykernel  # If not using a venv add `--user` flag
-python3 -m ipykernel install --user --name pycalibration --display-name "pycalibration"  # If not using a venv pick different name
+# If not using a venv add `--user` flag
+python3 -m pip install ipykernel
+# If not using a venv pick different name
+python3 -m ipykernel install --user --name pycalibration --display-name "pycalibration"
 ```
 
 This can be useful for Jupyter notebook tools as [max-jhub documentation](https://rtd.xfel.eu/docs/data-analysis-user-documentation/en/latest/jhub/)([max-jhub](https://max-jhub.desy.de/hub/login))
@@ -65,17 +92,12 @@ GitLab.
 
 To set up the keys:
 
-1.  Connect to Maxwell
-2.  Generate a new keypair with `ssh-keygen -o -a 100 -t ed25519`, you
-    can either leave this in the default location (`~/.ssh/id_ed25519`)
-    or place it into a separate directory to make management of keys
-    easier if you already have multiple ones. If you are using a
-    password for your keys please check this page to learn how to manage
-    them:
-    <https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent>
-3.  Add the public key (`id_ed25519.pub`) to your account on GitLab:
+1. Connect to Maxwell
+2. Generate a new keypair with `ssh-keygen -o -a 100 -t ed25519`, you can either leave this in the default location (`~/.ssh/id_ed25519`) or place it into a separate directory to make management of keys easier if you already have multiple ones.
+   If you are using a password for your keys please check this page to learn how to manage them: <https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent>
+3. Add the public key (`id_ed25519.pub`) to your account on GitLab:
     <https://git.xfel.eu/gitlab/profile/keys>
-4.  Add the following to your `~/.ssh/config` file
+4. Add the following to your `~/.ssh/config` file
 
 ```bash
 # Special flags for gitlab over SSH