From cb000c60672bd6058b4075659ca6df2da1f50859 Mon Sep 17 00:00:00 2001
From: raj_mathe <raj.dahya@math.uni-leipzig.de>
Date: Tue, 11 Oct 2022 16:45:39 +0200
Subject: [PATCH] main > main: README - added usage instructions

---
 README.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 01be729..1c2960b 100644
--- a/README.md
+++ b/README.md
@@ -18,4 +18,40 @@ See the [docs/*.ipynb](docs) files.
 **Note:** The Git provider _Gitea_ does not have a display format for ipynb-files.
 To properly view and run the notebooks, users require python v3.10.x and the jupyter module.
 To install the package requirements, call `just build`
-or `python3 -m pip install -r requirements.txt`.
+or `python3 -m pip install -r requirements.txt`.#
+
+## Usage ##
+
+To run the presentations:
+
+- Ensure you have a working copy of [**python 3.10.x**](https://www.python.org/downloads) on your system with rights to install packages.
+- Clone the repository.
+- Install the requirements. Navigate to the root of the repository and carry out:
+  ```bash
+  python3 -m pip install --disable-pip-version-check -r requirements.txt
+  # for Windows users:
+  py -3 -m pip install --disable-pip-version-check -r requirements.txt
+  ```
+- Start the desired notebooks using the [jupyter](https://jupyter.org) UI or run
+  ```bash
+  python3 -m jupyter notebook notebooks/xyz.ipynb
+  # for Windows users:
+  py -3 -m jupyter notebook notebooks/xyz.ipynb
+  ```
+  to run the notebook `docs/xyz.ipynb`.
+
+Alternatively we recommend the following:
+
+- Ensure you have a working copy of [**python 3.10.x**](https://www.python.org/downloads) on your system with rights to install packages.
+- Ensure you have **bash** (for Windows users see the [Git SCM](https://gitforwindows.org))
+  and the [**justfile**](https://github.com/casey/just#installation) tool
+  (Windows users may wish to install [Chocolatey](https://chocolatey.org/install) beforehand).
+- Clone the repository.
+- Navigate in a bash terminal to the root of the repository and make use of the following commands:
+  ```bash
+  # for setup:
+  just build
+  # to run the notebook docs/xyz.ipynb:
+  just run xyz
+  ```
+  (ensure that the extension is no included in the command!).