refactor: avoid redundant installation instructions and pin notebook version in documentation

README.md

@@ -19,55 +19,53 @@ already. If you have not then read the appendix section on [SSH Key Setup for Gi
 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 .`
+python3 -m pip install .  # Use 'pip install -e .' for editable install
 ```
 
 ### Installation into user home directory
 
-This is not recommended as `pycalibration` has pinned dependencies for
-stability, if you install it directly into you users home environment then it
-will downgrade/upgrade your local packages, which may cause major issues and may
-**break your local environment**, it is highly recommended to use the venv
-installation method instead.
-
-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. `pip install .` - install the pycalibration package (add `-e` flag for editable development installation)
-5. `export PATH=$HOME/.local/bin:$PATH` - make sure that the home directory is in the PATH environment variable
+**Warning:** This method is not recommended as `pycalibration` has pinned dependencies for
+stability. Installing directly into your user's home environment may downgrade/upgrade
+your local packages, potentially causing major issues and breaking your local environment.
+It is highly recommended to use the venv installation method instead.
 
-Copy/paste script:
+If you still wish to proceed with a user home directory installation, 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
-pyenv shell 3.11.9
 cd pycalibration
-pip install --user .  # `-e` flag for editable install, e.g. `pip install -e .`
+
+# Set up Python environment
+pyenv shell 3.11.9
+
+# Install pycalibration
+pip install --user .  # Use 'pip install --user -e .' for editable install
+
+# Update PATH
 export PATH=$HOME/.local/bin:$PATH
 ```
 
@@ -80,7 +78,7 @@ If you plan to work with Jupyter notebooks interactively, you have two main opti
 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
+python3 -m pip install notebook==6.5.1
 ```
 
 After installation, you can start a Jupyter notebook server by running: