From c9dafa93b41376bdbc0b98de3e823267f69e3d92 Mon Sep 17 00:00:00 2001
From: Max Melchert <maximilian.melchert@stud.hs-bochum.de>
Date: Fri, 14 Mar 2025 17:43:45 +0100
Subject: [PATCH] feat: add hidden details text in README
---
src/makefile/README.md | 171 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 162 insertions(+), 9 deletions(-)
diff --git a/src/makefile/README.md b/src/makefile/README.md
index edde22c..1e351a8 100644
--- a/src/makefile/README.md
+++ b/src/makefile/README.md
@@ -124,10 +124,34 @@ 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` |
+| Variable | Verwendung | Beispiel |
+| :------------ | :--------------- | :----------------- |
+| `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` |
+| Variable | Verwendung | Beispiel |
+| :------------------- | :------------------------- | :------------------ |
+| `LOCAL_PROJECT_DIR` | Client: Projektordner [^1] | `.` |
+| `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
---
--
GitLab