Refactor Dokumentation

README.md

@@ -22,10 +22,8 @@ werden:
 python --version
 ```
 
-
-
-Gängige Praxis ist es, Pythonumgebungen zu isolieren. Empfohlen wird dafür das Paket Poetry zu verwenden. Es kann um
-einen Terminalbefehl installiert werden. Mehr Informationen dazu finden sich [hier](https://python-poetry.org/docs/).
+Gängige Praxis ist es, Pythonumgebungen zu isolieren. Empfohlen wird dafür das Paket Poetry zu verwenden. Es kann mit
+einem Terminalbefehl installiert werden. Mehr Informationen dazu finden sich [hier](https://python-poetry.org/docs/).
 
 Sobald Python installiert ist, kann Cookiecutter mit folgendem Befehl installiert werden:
 
@@ -57,9 +55,9 @@ in jedem Fall zu empfehlen, da so die neueste Version des Templates verwendet wi
 Nun werden einige Fragen gestellt, um die Projektstruktur zu erstellen. Die Fragen sind relativ selbsterklärend, hier
 noch einige Tipps:
 
-- *Project Name*: Der Name des Projektes. Dieser sollte möglichst kurz und prägnant sein. Da der Name auch für die
+- *project_name*: Der Name des Projektes. Dieser sollte möglichst kurz und prägnant sein. Da der Name auch für die
   Ordnerstruktur verwendet wird, sollte er keine Sonderzeichen oder Leerzeichen enthalten. Zudem sollte er nicht zu lang sein.
-- *Select Course*: Hier wird der ADS Kurs ausgewählt, für den das Projekt erstellt wird. Hier ist es wichtig, die richtige
+- *course*: Hier wird der ADS Kurs ausgewählt, für den das Projekt erstellt wird. Hier ist es wichtig, die richtige
   Auswahl zu treffen, da sich die Projektstruktur je nach Kurs unterscheiden kann und vor allem die richtigen Python-Pakete 
   in der requirements.txt Datei eingetragen werden.
 - *jupyter_port*: Der Port, auf dem der Jupyter Notebook Server erreichbar sein soll. In der Regel ist der Standardwert
@@ -74,7 +72,7 @@ Nachdem alle Fragen beantwortet wurden, wird die Projektstruktur erstellt.
 ## Anpassen des Templates
 
 Das Repository besteht aus drei Teilen: Dem Template selbst, den Hooks und der Konfigurationsdatei `cookiecutter.json`.
-Alle Dateien, die Teil des Templates sind, befinden sich im dem Ordner `{{ cookiecutter.project_slug }}`. 
+Alle Dateien, die Teil des Templates sind, befinden sich in dem Ordner `{{ cookiecutter.__project_slug }}`. 
 In den Dateien und selbst Datei und Ordnernamen können Templatevariablen nutzen, die den Inhalt bzw. die Namen anpassen.
 Das ist bereits beim Ordnernamen beispielhaft zu erkennen.
 
@@ -92,4 +90,11 @@ Weitere Informationen dazu finden sich in der
 Die Datei `cookiecutter.json` enthält die Fragen, die dem Nutzer gestellt werden. Hier können auch Default-Werte angegeben werden.
 Die Inhalte der Variablen können im Template über `{{ cookiecutter.variable_name }}` abgerufen werden. Darüber hinaus
 können Variablen als private markiert werden, indem sie mit Unterstrichen beginnen. Diese Variablen werden nicht
-dem Nutzer gestellt, sondern können im Template genutzt werden. Beispiele befinden sich in der Datei.
+dem Nutzer gestellt, sondern können im Template genutzt werden. Beispiele befinden sich in der Datei.
+
+###  Ändern der Requirements für den Jupyter Notebook Server.
+Soll die Liste der vorinstallierten Python-Pakete für den Jupyter Notebook Server geändert werden, so kann dies in der
+Datei `requirements.txt` im Projektordner unter jupyter-server getan werden. Hier können weitere Pakete hinzugefügt 
+oder entfernt werden. In dieser Datei ist zu sehen, wie die Pakete je nach ADS-Modul unterschieden werden.
+Soll ein Paket für alle ADS-Module hinzugefügt werden, so muss es vor der if-then-Struktur eingetragen werden,
+anderfalls jeweils unter dem entsprechenden Modul. Die Kommentare in der Datei weisen den richtigen Weg.

{{ cookiecutter.__project_slug }}/README.md

@@ -1,36 +1,36 @@
 # ADS Projekt Template
 
 Dieser Projekt-Ordner enthält die Infrastruktur für die ADS-Übungen. Diese kann mithilfe von Podman oder Docker
-gestartet und benutzt werden. Die Infrastruktur besteht aus folgenden Komponenten:
+gestartet und benutzt werden. Sie besteht aus folgenden Komponenten:
 
 - Jupyter Notebook Server
 - PostgreSQL Datenbank
 - Adminer Datenbank-Admin-Tool
 
 ## Voraussetzungen
 
-Um das Template verwenden zu können, müssen einige Voraussetzungen erfüllt sein. Für das Erstellen der Projektstruktur
+Um das Template verwenden zu können, müssen einige Voraussetzungen erfüllt sein. Für das Erstellen des Projekts
 wird Cookiecutter verwendet. Cookiecutter ist ein Tool, mit dem Projektstrukturen aus Templates erstellt werden können.
 Für Cookiecutter wird Python benötigt und kann einfach über die Paketverwaltung installiert werden.
 
 ```shell
 pip install cookiecutter
 ```
 
-Da für den Betrieb der Infrastruktur lediglich Podman/Docker und Git benötigt werden, sind die Voraussetzungen relativ gering.
-Ein einigermaßen aktueller Rechner mit Linux, Windows oder macOS sollte ausreichen. Sollte ein
-Firmenrechner verwendet werden, muss aller Wahrscheinlichkeit nach im Vorhinein mit der IT-Abteilung des Unternehmens 
-gesprochen werden, denn beide Tools müssen installiert werden, ggf. sind Berechtigungen und Firewall-Regeln
+Da für den Betrieb der Infrastruktur lediglich Podman/Docker und Git benötigt werden, sind die weiterenVoraussetzungen relativ gering.
+Ein einigermaßen aktueller Rechner mit Linux, Windows oder macOS sollte ausreichen. Wird ein
+Firmenrechner verwendet, muss aller Wahrscheinlichkeit nach im Vorhinein mit der IT-Abteilung des Unternehmens 
+gesprochen werden, denn beide Tools müssen installiert werden und ggf. sind Berechtigungen und Firewall-Regeln
 anzupassen.
 
 Zudem wird für das Starten der Infrastruktur ein Terminal benötigt. Auf Linux und macOS lässt sich
 das Terminal mit dem Befehl "terminal" öffnen. Auf Windows kann das Terminal mit dem Befehl "cmd"
-gestartet werden. Idealerweise wird ein alternatives Terminal verwendet. Dazu mehr im nächsten Abschnitt.
+gestartet werden.
 
 ### Alternatives Terminal für Windows
 Das Standard-Terminal von Windows ist nicht besonders komfortabel und verwendet andere Befehle als
-Linux und macOS. Daher empfiehlt es sich, ein alternatives Terminal zu verwenden. Ein gutes Terminal
-ist das Git Bash Terminal, welches mit Git mitinstalliert wird. Es kann mit dem Befehl "git bash"
+Linux und macOS. Daher empfiehlt es sich, ein alternatives Terminal zu verwenden. Eine gute Alternative
+ist das Git Bash Terminal, welches mit Git installiert wird. Es kann mit dem Befehl "git bash"
 gestartet werden. 
 
 ## Installation
@@ -53,15 +53,14 @@ heruntergeladen werden.
 
 ## Verwendung
 
-Es wird davon ausgegangen, dass das Projekt mithilfe von Cookiecutter erstellt wurde. Es bietet sich an
-das Repository mit Git zu initialisieren. Dazu kann der folgende Befehl verwendet werden:
+Es wird davon ausgegangen, dass das Projekt mithilfe von Cookiecutter erstellt wurde und ein Terminal im Projektordner
+gestartet wurde. Zu Beginn sollte das Git-Repository initalisiert werden:
 
 ```
 git init
 ```
-
-Über die weitere Verwendung von Git erfahrt ihr in den Modulen. Das Repository kann gerne mit einer
-Git-Hosting-Plattform wie GitHub oder GitLab verbunden werden.
+Das Repository kann gerne mit einer Git-Hosting-Plattform wie GitHub oder GitLab verbunden werden.
+Über die weitere Verwendung von Git werden Lerninhalte in den ADS-Modulen zur Verfügung gestellt.
 
 ### Setzen der Umgebungsvariablen
 Um die Infrastruktur starten zu können, müssen noch einige Umgebungsvariablen gesetzt werden.
@@ -70,45 +69,49 @@ von Docker automatisch erkannt werden. Ein wichtiger Aspekt dabei ist, dass .env
 in ein Repository eingecheckt werden sollten. Daher wurde die .env-Datei in die .gitignore-Datei eingetragen.
 Dadurch wird sie nicht im Repository angezeigt und kann nicht aus Versehen eingecheckt werden.
 Es befindet sich bereits eine .env-Datei im Projekt. Diese enthält auch bereits die notwendigen Variablen.
-Die sollten jedoch angepasst werden. Dazu sollte die .env Datei geöffnet werden und die Werte hinter dem
+Die sollten jedoch angepasst werden. Dazu sollte die .env Datei geöffnet und die Werte hinter dem
 Gleichheitszeichen verändert werden.
 
-Die Variablen sollten sich zum größten Teil selbst erklären. Erwähnenswert ist lediglich der Jupyter Token.
+Die Variablen sollten sich zum größten Teil selbst erklären. Erwähnenswert ist zum einen der Jupyter Token.
 Dieser wird benötigt, um auf Jupyter zugreifen zu können. Wenn die Notebooks im Browser geöffnet werden, wird nach diesem
 Token gefragt. Er muss aus der .env-Datei kopiert werden.
 
+Auf der anderen Seite kann es für erfahrene Nutzer notwendig sein, die Ports für die beiden Container Jupyter Notebook
+bzw Adminer anzupassen. Werden diese vom Host-System bereits genutzt, starten diese Container nicht und es ist notwendig
+andere Zahlen einzutragen. Bei Problemen bzw. Fragen kann dieser Punkt mit dem Dozent bzw. der Dozentin geklärt werden.
+
 ## Starten der Infrastruktur
 
-Um die Infrastruktur zu starten, muss in das Projektverzeichnis gewechselt werden. Sollte als
-Container-Management-Tool Podman verwendet wurden sein, so wird lediglich das Wort 'docker' durch 'podman' in den
-folgenden Befehlen verwendet. Folgender Befehl startet die Infrastruktur:
+Um die Infrastruktur zu starten, wird aus dem Projektverzeichnis heraus Docker Compose verwendet. Sollte als
+Container-Management-Tool Podman Verwendung finden, so wird lediglich das Wort 'docker' durch 'podman' in den
+folgenden Befehlen ersetzt. Die Infrastruktur kann wie folgt gestartet werden:
 
 ```shell
 docker compose up -d
 ```
 
-Nachdem diese gestartet wurde, sieht man im Docker/Podman Desktop die Container.
-Wenn alles geklappt hat, werden drei Container jeweils mit einem grünen Symbol angezeigt.
+Nachdem dies geschehen ist, sieht man im Docker/Podman Desktop die Container.
+Bei Erfolg, werden drei Container jeweils mit einem grünen Symbol angezeigt.
 
-Im Docker Desktop sind zudem die Links hinterlegt, um auf die verschiedenen Komponenten zuzugreifen.
+Im Docker/Podman Desktop sind zudem die Links hinterlegt, um auf die verschiedenen Komponenten zuzugreifen.
 Wichtig sind die beiden Links zu Jupyter und Adminer. Diese können im Browser geöffnet werden in dem
 auf die Zahlen 8888:8888 oder 8080:8080 geklickt wird. Der Standartbrowser sollte sich dann öffnen.
 
 ### Installation zusätzlicher Pakete
+
 Um zusätzliche Pakete in Jupyter zu installieren, müssen diese in der requirements.txt-Datei eingetragen werden.
-Diese befindet sich im Ordner jupyter-server. Nachdem die Pakete eingetragen wurden, muss die
-Infrastruktur neu gestartet werden. Dazu kann folgender Befehl ausgeführt werden:
+Diese befindet sich im Ordner jupyter-server. Nachdem die Pakete eingetragen wurden, wird die Infrastruktur
+neu gestartet. Dabei muss der Jupyter Container neu gebaut werden. Der Befehl zum starten (siehe oben) wird durch
+das --build Flag erweitert. die folgenden beiden Befehle zeigen, wie die Infrastruktur zunächst beendet wird, um
+sie dann inklusive dem neuen Bauen zu starten:
 
 ```shell
 docker compose down
 docker compose up -d --build
 ```
 
-Das build flag sorgt dafür, dass der Jupyter Container neu gebaut wird und die neuen Pakete installiert werden.
-
-
 ## Stoppen der Infrastruktur
-Nach dem Beenden der Übungen sollte die Infrastruktur wieder gestoppt werden. Dazu kann folgender Befehl
+Nach dem Beenden der Übungen kann die Infrastruktur beendet werden. Der Befehl dazu wurde soeben vorgestellt:
 
 ```shell
 docker compose down

{{ cookiecutter.__project_slug }}/jupyter-server/requirements.txt

@@ -1,3 +1,5 @@
+# Add global requirements here
+
 {%- if cookiecutter.course == "ADS-01" -%}
 # Add ADS-01 course requirements here