feat: add hidden details text in README

src/makefile/README.md

@@ -125,9 +125,33 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 ### Server
 
 | Variable      | Verwendung       | Beispiel           |
-| :------------ | :---------------- | :----------------- |
-| `SERVER_USER` | Server: User Name | `mmustermann`      |
-| `SERVER_HOST` | Server: Host Name | `hyrican-1-extern` |
+| :------------ | :--------------- | :----------------- |
+| `SERVER_USER` | Server: Username | `mmustermann`      |
+| `SERVER_HOST` | Server: Hostname | `hyrican-1-extern` |
+
+<details>
+<summary>Details anzeigen</summary>
+
+#### `SERVER_USER`
+
+> Wird vom Server-Admin vergeben.
+
+#### `SERVER_HOSTNAME`
+
+> Kann in verschiedenen Formaten vorliegen:
+
+| Format               | Beschreibung                 | Beispiel             |
+| :------------------- | :--------------------------- | :------------------- |
+| IP-Address (private) | numerisch; lokales Netz      | `192.168.1.100`      |
+| IP-Address (public)  | numerisch; öffentliches Netz | `203.0.113.1`        |
+| FQDN                 | vollständiger Domänenname    | `server.example.com` |
+| Hostname             | einfacher Name ohne Domäne   | `hyrican-1`          |
+| Alias                | alternativer Name; Verweis   | `hyrican-1-extern`   |
+
+In der Regel übermittelt der Server-Admin dem neu freigeschalteten User eine SSH-Config.
+Die Verwendung der dort definierten Aliases wird empfohlen.
+
+</details>
 
 ### Python Environment
 
@@ -138,12 +162,67 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 | `PYTHON_VERSION`    | Python: Gewünschte Version       | `3.10`                             |
 | `PYTHON_PACKAGES`   | Python: Benötigte Pakete         | `tensorflow-cpu matplotlib optuna` |
 
+<details>
+<summary>Details anzeigen</summary>
+
+#### `SERVER_CONDA_PATH`
+
+> Definiert dem Pfad der _Conda_-Installation auf dem Server.
+
+Auf den Servern `server-*`, `hyrican-*` und `nbb-*` ist _Conda_ unter `/opt/conda` installiert.
+
+#### `SERVER_CONDA_ENV`
+
+> Definiert den Pfad des _Conda-Environments_.
+
+Die Erstellung neuer _Conda Environments_ ist ohne Admin-Rechte global nicht möglich.
+Deshalb müssen sie lokal erstellt und installiert werden.
+Die vorkonfigurierte _Makefile_ schlägt den Ordner `~/envs` im Home-Verzeichnis vor.
+
+**WICHTIG:** Möchte man sich manuell auf einem der Server anmelden und bspw. Pakete installieren, muss das _Conda Environment_ aktiviert werden:
+
+```bash
+conda activate ~/envs/ml
+```
+
+#### `PYTHON_VERSION`
+
+> Nach Bedarf konfigurierbar
+
+#### `PYTHON_PACKAGES`
+
+> Nach Bedarf konfigurierbar.
+
+Vorkonfiguriert ist das `ml`-Environment mit seinen Packages, wie es in _[install-python-tensorflow-gym](https://gitlab.cvh-server.de/ckaufmann/install-python-tensorflow-gym)_ vorschlägt.
+Zusätzlich benötigte Pakete müssen – mit Leerzeichen getrennt – an `PYTHON_PACKAGES` angehängt werden.
+
+</details>
+
 ### Project Paths
 
 | Variable             | Verwendung                 | Beispiel            |
-| :------------------- | :------------------------- | :------------------- |
+| :------------------- | :------------------------- | :------------------ |
 | `LOCAL_PROJECT_DIR`  | Client: Projektordner [^1] | `.`                 |
-| `REMOTE_PROJECT_DIR` | Server: Projektordner [^2] | `~s/akis/my_project` |
+| `REMOTE_PROJECT_DIR` | Server: Projektordner [^2] | `~/akis/my_project` |
+
+<details>
+<summary>Details anzeigen</summary>
+
+#### `LOCAL_PROJECT_DIR`
+
+> Definiert den Pfad des Projektordners auf dem **lokalen Rechner**.
+
+Er wird relativ zur _Makefile_ angegeben.
+Liegt die _Makefile_ also direkt im Projektordner, ist `LOCAL_PROJECT_DIR := .`.
+
+#### `REMOTE_PROJECT_DIR`
+
+> Definiert den Pfad des Projektordners auf dem **Server**.
+
+Er wird absolut oder relativ zum Home-Verzeichnis angegeben.
+Also bspw. `~/akis/my_project` oder `/home/mmustermann/akis/my_project`.
+
+</details>
 
 ### Project Files
 
@@ -152,6 +231,26 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 | `MAIN_SCRIPT` | Auszuführendes Python-Script [^1] | `main.py`      |
 | `LOG_FILE`    | Log-Datei (optional) [^1]         | `progress.log` |
 
+<details>
+<summary>Details anzeigen</summary>
+
+#### `MAIN_SCRIPT`
+
+> Definiert das _Python_-Script, welches später durch die _Makefile_ auf dem Server ausgeführt wird.
+
+Sollte es notwendig sein, dass mehrere Scripts bspw. nacheinander ausgeführt werden, ist es empfehlenswert eine `main.py` zu erstellen.
+Dieses `main.py` kann dann alle anderen Scripts ausführen.
+
+#### `LOG_FILE`
+
+> Definiert die Datei, in der das _Python_-Script einen Log schreib.
+
+Logs beinhalten meist Statusmeldungen über den Programmablauf und geben Aufschluss über Fortschritt, Fehler und Erfolg.
+Die Verwendung einer Log-File ist optional.
+Ist sie vorhanden, kann sie mit `make log` angesehen werden; neue Einträge werden "live" aktualisiert und angezeigt.
+
+</details>
+
 ### File Transfer
 
 | Variable                | Verwendung                    | Beispiel                     |
@@ -160,12 +259,64 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 | `LOCAL_DOWNLOAD_DIR`    | Client: Download-Ordner [^1]  | `output`                     |
 | `REMOTE_DOWNLOAD_FILES` | Server: Download-Dateien [^1] | `output/*.svg output/*.pkl`  |
 
+<details>
+<summary>Details anzeigen</summary>
+
+#### `LOCAL_UPLOAD_FILES`
+
+> Definiert – relativ zum Projektordner –, welche Dateien auf den Server hochgeladen werden sollen.
+
+Dazu ein paar Beispiele:
+
+| `LOCAL_UPLOAD_FILES`   | Bedeutung                                       |
+| :--------------------- | :---------------------------------------------- |
+| `.`                    | gesamter Projektordner                          |
+| `main.py scripts data` | Main-Script, Scripts-Ordner, Data-Ordner        |
+| `main.py data/*.pkl`   | Main-Script; alle Pickle-Dateien im Data-Ordner |
+
+#### `LOCAL_DOWNLOAD_DIR`
+
+> Definiert – relativ zum Projektordner – den Pfad, in dem vom Server heruntergeladene Output-Dateien gespeichert werden sollen.
+
+Dieser kann dem selben Ordner entsprechen, wie er auf dem Server gespiegelt ist.
+Er kann jedoch auch ein anderer sein und bspw. `downloads` heißen.
+
+#### `REMOTE_DOWNLOAD_FILES`
+
+> Definiert – relativ zum Projektordner –, welche Output-Dateien vom Server heruntergeladen werden sollen.
+
+Es können sowohl ganze Ordner, als auch einzelne Dateien ausgewählt werden.
+Dazu ein paar Beispiele:
+
+| `REMOTE_DOWNLOAD_FILES`                     | Bedeutung                                                                       |
+| :------------------------------------------ | :------------------------------------------------------------------------------ |
+| `outputs`                                   | alle Dateien im Output-Ordner                                                   |
+| `outputs/*.csv outputs/*.pkl outputs/*.svg` | alle CSV-, PKL- und SVG-Dateien des Output-Orderns                              |
+| `outputs img/*.png progress.log             | alle Dateien im Output-Ordner; alle PNG-Dateien im Image-Ordner; eine Log-Datei |
+
+</details>
+
 ### Misc
 
 | Variable              | Verwendung                         | Beispiel |
 | :-------------------- | :--------------------------------- | :------- |
 | `COPY_LINKS_AS_FILES` | Server: Kopiert Symlinks als Datei | `false`  |
 
+<details>
+<summary>Details anzeigen</summary>
+
+#### `COPY_LINKS_AS_FILES`
+
+> Kopiert symbolische Links als Datei
+
+Wenn in den Projektordnern symbolische Links ("symlinks", "symbolic links") liegen, werden diese von der _Makefile_ **nicht wie Dateien** behandelt.
+Sie werden unverändert als _Symlinks_ auf den Server kopiert.
+
+In manchen Anwendungsfällen ist es jedoch gewollt, dass die Verlinkung aufgelöst und die Links als Dateien kopiert werden.
+Für diesen Fall muss `COPY_LINKS_AS_FILES` auf `true` gesetzt werden.
+
+</details>
+
 [^1]: Relativer Pfad zum Projektordner
 [^2]: Absoluter Pfad
 
@@ -180,7 +331,7 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 | `run`      | Führt Python Script aus                   |     Server      |
 | `kill`     | Bricht Python Script ab                   |     Server      |
 | `log`      | Zeigt Log-Datei (optional) an             |     Client      |
-| `download` | Läd Outputdateien herunter                | Server → Client |
+| `download` | Läd Output-Dateien herunter               | Server → Client |
 | `delete`   | Löscht Projektdateien                     |     Server      |
 
 ---
@@ -191,9 +342,11 @@ Sie werden durch den Aufruf von `make download` im zuvor definierten Ordner `LOC
 - [ ] Datasets über NFS
 - [ ] Benachrichtigung bei Abbruch/Erfolg
   - [ ] Slack
+  - [ ] E-Mail
   - [ ] Matrix
 - [ ] parallele Ausführung mehrerer Scripts
 - [ ] docs: get local python packages; append to `PYTHON_PACKAGES`
+- [ ] ggf. mehrere Log-Files
 
 ---