[DOC] up-to-date installation instructions

Author: balbasty

README.md

@@ -1,6 +1,6 @@
 ```
    ___  ____  __  __
-  / __)(  _ \(  \/  )  
+  / __)(  _ \(  \/  )
   \__ \ )___/ )    (   Statistical Parametric Mapping
   (___/(__)  (_/\/\_)  SPM - https://www.fil.ion.ucl.ac.uk/spm/
 ```
@@ -15,22 +15,81 @@ Copyright (C) 1991,1994-2025 Wellcome Centre for Human Neuroimaging
 ![PyPI - Version](https://img.shields.io/pypi/v/spm-python)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/spm/spm-python/.github%2Fworkflows%2Frun_unit_tests.yml)
 
-
 > [!WARNING]
-> This project is **currently under construction** and might contain bugs. **If you experience any issues, please [let us know](https://github.com/spm/spm-python/issues)!**
+> This project is **young** and might contain bugs.
+> **If you experience any issues, please [let us know](https://github.com/spm/spm-python/issues)!**
 
+## Installation instructions
 
-## Installation instructions: 
-0. Install Python and Pip. Python installation made from Microsoft Store on Windows will not work (raises DeclarativeService.dll not found), install it from Python website. 
-> [!WARNING]
-> spm-python currently requires Python 3.12.
+### Important - Windows
+
+Python installation made from Microsoft Store on Windows will not work
+(raises DeclarativeService.dll not found), install it from Python website.
+
+### Important - Python/MATLAB compatibility
+
+Specific versions of MATLAB are compatible with
+[specific versions of Python](https://uk.mathworks.com/support/requirements/python-compatibility.html).
+
+By default, spm-python uses:
+- Python 3.6: R2020b
+- Python 3.7: R2021b
+- Python 3.8: R2023a
+- Python 3.9-3.12: R2025a
+- Python 3.13: Unsupported
+
+### Option 1 - Install the MATLAB runtime on first use
 
-1. Install [Matlab Runtime 2024b](https://uk.mathworks.com/products/compiler/matlab-runtime.html) 
+1. Install SPM-Python
+   ```shell
+   pip install spm-python
+   ```
+2. Run spm
+   ```shell
+   spm
+   ```
+3. Follow the instructions
+
+- **Advantages**
+  - Installs the runtime that is required for your python version
+  - Does not resintall anything if a compatible runtime already exists
+- **Drawbacks**
+  - May need to be run in proviledged mode (e.g., `sudo`)
+  - May be fiddly on Windows
+
+### Option 2 - Install the MATLAB runtime manually
+
+1. Install the appropriate [MATLAB Runtime](https://uk.mathworks.com/products/compiler/matlab-runtime.html)
 2. Install SPM:
    ```python
    pip install spm-python
    ```
-3. That's all!
+
+- **Advantages**
+  - Graphical interface for installing the runtime
+- **Drawbacks**
+  - The correct runtime must be selected for your python version
+
+### Option 3 - Install the MATLAB runtime using an installation script
+
+1. Install SPM-Python
+   ```shell
+   pip install spm-python
+   ```
+2. Run the installer
+   ```shell
+   install_matlab_runtime --version R2025a --yes
+   ```
+
+- **Advantages**
+  - Exposes installation options (`install_matlab_runtime --help`)
+  - Allows any runtime version to be installed. One may do:
+    ```shell
+    pip install spm-python[R2023b]
+    install_matlab_runtime --version R2023b
+    ```
+- **Drawbacks**
+  - For advanced users
 
 ## Minimal example
 Here is a minimal set of examples showcasing changes to do to use existing Matlab code in Python (taken from the [OPM tutorial](https://www.fil.ion.ucl.ac.uk/spm/docs/tutorials/opm/evoked/)).
@@ -40,14 +99,14 @@ In Matlab:
 ```Matlab
  spm('defaults', 'eeg');
 ```
-In Python: 
+In Python:
 ```Python
 from spm import *
 spm('defaults', 'eeg')
 ```
 
 ### 2. Constructing objects
-In Matlab: 
+In Matlab:
 ```Matlab
 S = [];
 S.data = 'OPM_meg_001.cMEG';
@@ -57,22 +116,22 @@ D = spm_opm_create(S);
 In Python, create a `Struct()` instead of a `struct`:
 ```Python
 S = Struct()
-S.data='OPM_meg_001.cMEG'
-S.positions='OPM_HelmConfig.tsv'
+S.data = 'OPM_meg_001.cMEG'
+S.positions = 'OPM_HelmConfig.tsv'
 D = spm_opm_create(S)
 ```
 Here, `D` will be a `meeg` object which contains a virtual representation of the Matlab object. Class methods should work as expected, e.g.:
 ```Python
 D.fullfile()
 >>> './OPM_meg_001.mat'
 ```
-Note that the alternative call that exist in Matlab (i.e., `fullfile(D)`) will not work.  
+Note that the alternative call that exist in Matlab (i.e., `fullfile(D)`) will not work.
 
 ### 3. Creating and handling figures
-In Matlab: 
+In Matlab:
 ```Matlab
 S = [];
-S.triallength = 3000; 
+S.triallength = 3000;
 S.plot = 1;
 S.D = D;
 S.channels = 'MEG';
@@ -94,7 +153,7 @@ This opens a Matlab figure, but we do not have the possibility of manipulating i
 In Matlab:
 ```Matlab
 S = [];
-S.triallength = 3000; 
+S.triallength = 3000;
 S.plot = 1;
 S.D = mD;
 [~,freq] = spm_opm_psd(S);
@@ -103,17 +162,17 @@ In Python, the number of output arguments must be specified by the `nargout` key
 ```Python
 S = Struct()
 S.triallength = 3000
-S.plot=1
-S.D=mD
+S.plot = 1
+S.D = mD
 [_,freq] = spm_opm_psd(S, nargout=2)
 ```
 
-### 5. Other examples 
+### 5. Other examples
 In Matlab:
-```Matlab 
-S=[];
-S.D=D;
-S.freq=[10];
+```Matlab
+S = [];
+S.D = D;
+S.freq = [10];
 S.band = 'high';
 fD = spm_eeg_ffilter(S);
 
@@ -123,7 +182,7 @@ S.freq = [70];
 S.band = 'low';
 fD = spm_eeg_ffilter(S);
 ```
-In Python: 
+In Python:
 ```Python
 S = Struct()
 S.D = D