Improved install docs

README.md

@@ -2,53 +2,66 @@
 
 This repository contains Jupyter Notebooks that can be used as training materials for understanding how the PDBe REST API works, and provides a number of examples of answering specific questions about PDB entries using the API.
 
-## Getting Started
 
-Either use Binder to use the notebook:
+## Getting started with Docker (recommended)
 
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PDBeurope/pdbe-api-training/master)
+This option launches the summer school notebooks in a Docker container. This is the recommended way to run the notebooks as it ensures that all dependencies are correctly installed and that the notebooks will run as expected.
 
-Or
+Make sure your [Docker](https://docs.docker.com/engine/install/) is running on your machine before executing the following commands:
 
-You will need to have Jupyter installed on your machine. For Linux/OSX machines, simply type:
+### Clone the repository
+```console
+git clone https://github.com/PDBeurope/pdbe-api-training .
+cd /path/to/your/pdbe-api-training/
+```
 
+### Build the Docker container (you only need to do this once)
+```console
+docker build -t pdbe-api-training .
 ```
-pip3 install --upgrade pip
-pip3 install jupyter
+
+### Run the Docker container
+```console
+docker run -p 8888:8888 -v /path/to/your/pdbe-api-training/pdbe_tutorial_2024/:/pdbe_api_tutorial/pdbe_tutorial_2024 pdbe-api-training
 ```
 
-For Windows machines (optionally also for Linux/OSX) you can install Jupyter with conda-forge:
-https://conda-forge.org/
+Now open your browser and go to `http://localhost:8888/` and you should see the Jupyter Notebook interface. The `-v` flag ensures changes you make to the notebooks will be saved in the `pdbe_tutorial_2024` directory in the repository cloned to your local machine.
 
-### Prerequisites
+## Getting started with Binder
 
-If installing using Anaconda, there is no additional prerequisites. If installing using pip3, you will need to have Python3 on your machine, and of course pip3
+Notebooks can also be run on cloud via Binder. Click on the badge below to launch the notebooks in Binder:
 
-### Installing
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PDBeurope/pdbe-api-training/master)
 
-From command line on Unix machine these would be the steps setting up everyone:
 
+## Getting started with Python and Jupyter
+
+You will need to have Python3.10, pip3 and Jupyter installed on your machine.
+
+### Upgrade pip3
+```console
+pip3 install --upgrade pip
 ```
+
+For Windows machines (optionally also for Linux/OSX) you can install Jupyter with conda-forge:
+https://conda-forge.org/
+
+### Clone the repository
+
+```console
 mkdir pdbe_jupyter
 cd pdbe_jupyter
 git clone https://github.com/PDBeurope/pdbe-api-training .
-jupyter notebook
 ```
 
-Jupyter Notebook will open a window in your browser, and you can select the specific notebooks you would like to view.
-
-
-## Install and run with Docker
-
-Make sure your Docker client is running and then run:
-
-```shell
-cd /path/to/your/pdbe-api-training/
-docker build -t pdbe-api-training .
-docker run -p 8888:8888 -v /path/to/your/pdbe-api-training/pdbe_tutorial_2024/:/pdbe_api_tutorial/pdbe_tutorial_2024 pdbe-api-training
+### Install the dependencies and start Jupyter
+```console
+cd pdbe-api-training
+pip3 install -r requirements.txt
+jupyter ./pdbe_tutorial_2024
 ```
 
-Now open your browser and go to `http://localhost:8888/` and you should see the Jupyter Notebook interface. The `-v` flag ensures changes you make to the notebooks will be saved in the `pdbe_tutorial_2024` directory in the repository cloned to your local machine.
+Jupyter Notebook will open a window in your browser, and you can select the specific notebooks you would like to view.
 
 
 ## Authors