feat(docs): migrate to zensical, re-structure docs

2025-12-01 10:36:36 +01:00
parent 9f1dfa1030
commit cee3379203
22 changed files with 1528 additions and 32 deletions
--- a/docs/admin.md
+++ b/docs/admin.md
@@ -1,25 +0,0 @@
-# Adminbereich
-
-Der Adminbereich ist nur freigeschaltet, wenn der angemeldete Nutzer die Rolle admin hat. Hier können neue Nutzer angelegt, bestehende Nutzer bearbeitet oder gelöscht werden. Zusätzlich können die Daten der ProfessorInnen bearbeitet werden.
-
-Die Verschiedenen Aktionen können über das Dropdown-Menü ausgewählt werden.
-
-## Nutzer anlegen
-![Nutzer anlegen](images/admin_create_user.png)
-
-Hier kann ein neuer Nutzer angelegt werden. Dazu müssen der Nutzername, das Password und die Rolle angegeben werden. Die Rolle kann frei vergeben, oder aus dem Dropdown ausgewählt werden.
-
-Über den Knopf **Anlegen** wird der Nutzer angelegt.
-
-## Nutzer bearbeiten
-![Nutzer bearbeiten](images/admin_edit_user.png)
-
-Hier können die Verschiedenen Nutzer bearbeitet oder gelöscht werden. Hat der ausgewählte Nutzer die Rolle admin, so kann dieser nicht gelöscht werden.
-Um einen Nutzer zu löschen, muss sowohl ein Haken bei **Löschen** gesetzt werden, als auch der Knopf **Löschen** gedrückt werden.
-
-## Lehrperson bearbeiten
-
-![Lehrperson bearbeiten](images/admin_edit_prof.png)
-Hier können die Daten der Lehrperson bearbeitet werden, oder die Lehrperson gelöscht werden. Um eine Lehrperson zu löschen, darf kein Aktiver Apparat vorhanden sein, sowie keine ELSA Aufträge vorhanden sein. 
-
-Um eine Lehrperson zu bearbeiten, muss der Name im Dropdown bei "Alte Angaben" ausgewählt werden. Die Alten Daten werden nun in der Maske angezeigt. Die neuen Daten können nun im unteren Bereich eingegeben werden. Über den Knopf **Aktualisieren** werden die Daten gespeichert.
--- a/docs/allgemein/hauptoberflaeche.md
+++ b/docs/allgemein/hauptoberflaeche.md
@@ -0,0 +1,108 @@
+# Hauptoberfläche
+
+![Hauptoberfläche](../images/mainUI.png){ loading=lazy }
+
+Die Hauptoberfläche des SemesterapparatsManager besteht aus drei Hauptbereichen, die über Tabs erreichbar sind:
+
+## Navigation
+
+<div class="grid cards" markdown>
+
+-   :lucide-book-plus:{ .lg .middle } **Anlegen**
+
+    ---
+
+    Neue Semesterapparate erstellen, bestehende aktualisieren oder löschen.
+
+    [:octicons-arrow-right-24: Zum Anlegen](../semesterapparat/anlegen.md)
+
+-   :lucide-search:{ .lg .middle } **Suchen/Statistik**
+
+    ---
+
+    Semesterapparate suchen, filtern und Statistiken einsehen.
+
+    [:octicons-arrow-right-24: Zur Suche](../semesterapparat/suche.md)
+
+-   :lucide-file-text:{ .lg .middle } **ELSA**
+
+    ---
+
+    Elektronische Semesterapparate anlegen und Zitate erstellen.
+
+    [:octicons-arrow-right-24: Zu ELSA](../elsa/anlegen.md)
+
+</div>
+
+---
+
+## Übersichtstabelle
+
+![Übersichtstabelle](../images/main_overview.png){ loading=lazy }
+
+In diesem Bereich werden alle erstellten Semesterapparate angezeigt. 
+
+!!! tip "Tipp: Doppelklick"
+    Über einen **Doppelklick** auf einen Apparat werden alle Details geladen und in den Apparatdetails angezeigt.
+
+### Verfügbare Aktionen
+
+| Knopf | Funktion |
+|-------|----------|
+| :lucide-printer: **Übersicht erstellen** | Erstellt eine druckbare Übersicht der angezeigten Apparate für das Regal |
+| :lucide-plus: **neu. App anlegen** | Schaltet die Apparatdetails frei für einen neuen Apparat |
+| :lucide-x: **Auswahl abbrechen** | Entfernt alle Daten und deaktiviert die Apparatdetails |
+
+!!! note "Hinweis: Übersicht drucken"
+    Die Übersicht wird per Mail an den konfigurierten Drucker geschickt. Vor dem Drucken erfolgt eine Bestätigungsabfrage.
+
+---
+
+## Einstellungen
+
+Die Einstellungen erreichen Sie über das Menü oder das :lucide-settings: Icon.
+
+![Einstellungen](../images/settings.png){ loading=lazy }
+
+!!! info "Automatisches Wiederherstellen"
+    Die zuletzt geöffnete Seite wird automatisch beim nächsten Start geöffnet.
+
+### Datenbank
+
+Hier sind alle Informationen zur Datenbank sowie den temporären Daten hinterlegt.
+
+!!! warning "Mehrere Nutzer"
+    Sollte die Anwendung von mehreren Nutzern benutzt werden, sollte der Datenbankpfad nur in Absprache geändert werden. Ansonsten kann es zu Synchronisationsproblemen kommen.
+
+### Zotero
+
+![Zotero Einstellungen](../images/settings_zotero.png){ loading=lazy }
+
+Konfigurieren Sie hier die Zugangsdaten für Zotero, die für die [ELSA-Zitate](../elsa/zitieren.md) benötigt werden.
+
+### E-Mail
+
+![E-Mail Einstellungen](../images/settings_mail.png){ loading=lazy }
+
+=== "Allgemein"
+
+    Zugangsdaten für den SMTP-Mailversand. Diese werden für Benachrichtigungen an Dozenten benötigt.
+
+=== "Signatur"
+
+    Die Signatur wird automatisch an jede ausgehende Mail angehängt.
+
+### Icons
+
+![Icon Einstellungen](../images/settings_icons.png){ loading=lazy }
+
+Übersicht der aktuellen Icons und verfügbaren Farbschemata.
+
+---
+
+## Speichern der Einstellungen
+
+Über den Knopf **Ok** werden die Einstellungen gespeichert. 
+
+!!! success "Sofortige Übernahme"
+    Die meisten Einstellungen werden sofort übernommen. Sollte ein Neustart erforderlich sein, werden Sie darüber informiert.
--- a/docs/allgemein/index.md
+++ b/docs/allgemein/index.md
@@ -0,0 +1,31 @@
+# Allgemein
+
+Willkommen in der Dokumentation des **SemesterapparatsManager**! In diesem Abschnitt finden Sie alle grundlegenden Informationen zum Programm.
+
+<div class="grid cards" markdown>
+
+-   :lucide-info:{ .lg .middle } **Info**
+
+    ---
+
+    Erfahren Sie mehr über den SemesterapparatsManager und seine Funktionen.
+
+    [:octicons-arrow-right-24: Mehr erfahren](info.md)
+
+-   :lucide-download:{ .lg .middle } **Installation**
+
+    ---
+
+    Installieren Sie den SemesterapparatsManager in wenigen Schritten.
+
+    [:octicons-arrow-right-24: Zur Installation](installation.md)
+
+-   :lucide-layout-dashboard:{ .lg .middle } **Hauptoberfläche**
+
+    ---
+
+    Lernen Sie die Benutzeroberfläche des Programms kennen.
+
+    [:octicons-arrow-right-24: Zur Übersicht](hauptoberflaeche.md)
+
+</div>
--- a/docs/allgemein/info.md
+++ b/docs/allgemein/info.md
@@ -0,0 +1,57 @@
+# Info
+
+## Über den SemesterapparatsManager
+
+Der **SemesterapparatsManager** ist ein grafisches Werkzeug zur Verwaltung von Semesterapparaten an der Pädagogischen Hochschule Freiburg. 
+
+!!! abstract "Was ist ein Semesterapparat?"
+    Ein Semesterapparat ist eine Sammlung von Literatur, die von Dozenten für ihre Lehrveranstaltungen zusammengestellt wird. Die Bücher werden in der Bibliothek bereitgestellt und können von Studierenden eingesehen werden.
+
+## Funktionen
+
+Die Anwendung ermöglicht eine benutzerfreundliche Verwaltung von physischen und digitalen Semesterapparaten:
+
+<div class="grid cards" markdown>
+
+-   :lucide-book-plus:{ .lg .middle } **Anlegen**
+
+    ---
+
+    Erstellen Sie neue Semesterapparate mit allen notwendigen Informationen zu Dozenten, Fächern und Literatur.
+
+-   :lucide-search:{ .lg .middle } **Suchen & Statistik**
+
+    ---
+
+    Durchsuchen Sie bestehende Apparate und erhalten Sie statistische Auswertungen.
+
+-   :lucide-file-text:{ .lg .middle } **ELSA**
+
+    ---
+
+    Verwalten Sie elektronische Semesterapparate (ELSA) mit automatischer Zitat-Erstellung via Zotero.
+
+-   :lucide-mail:{ .lg .middle } **Kommunikation**
+
+    ---
+
+    Versenden Sie automatisierte E-Mails an Dozenten bei Erstellung oder Löschung von Apparaten.
+
+</div>
+
+## Technische Details
+
+| Eigenschaft | Wert |
+|-------------|------|
+| **Programmiersprache** | Python 3.10+ |
+| **GUI-Framework** | PySide6 (Qt) |
+| **Datenbank** | SQLite |
+| **Zitat-System** | Zotero Integration |
+| **Stil** | DGPs (Deutsche Gesellschaft für Psychologie) |
+
+## Entwicklung
+
+Der SemesterapparatsManager wurde entwickelt von **Alexander Kirchner** für die Pädagogische Hochschule Freiburg.
+
+!!! info "Open Source"
+    Der Quellcode ist auf GitHub verfügbar und kann nach Absprache eingesehen werden.
--- a/docs/allgemein/installation.md
+++ b/docs/allgemein/installation.md
@@ -0,0 +1,85 @@
+# Installation
+
+## Voraussetzungen
+
+Bevor Sie den SemesterapparatsManager installieren können, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:
+
+- [x] Windows 10/11 oder höher
+- [x] Internetzugang für Katalog-Abfragen
+- [x] Optional: Zotero-Account für ELSA-Funktionen
+
+## Installation
+
+### Für Endanwender
+
+=== "Portable Version"
+
+    1. Laden Sie die neueste Version von der Release-Seite herunter
+    2. Entpacken Sie die ZIP-Datei in einen Ordner Ihrer Wahl
+    3. Starten Sie `SemesterapparatsManager.exe`
+
+=== "Installer"
+
+    1. Laden Sie den Installer herunter
+    2. Führen Sie die Setup-Datei aus
+    3. Folgen Sie den Anweisungen des Installationsassistenten
+    4. Starten Sie das Programm über das Startmenü
+
+### Für Entwickler
+
+!!! note "Entwicklerinstallation"
+    Diese Anleitung ist für Entwickler gedacht, die den Quellcode bearbeiten möchten.
+
+#### Mit UV (empfohlen)
+
+```bash
+# Repository klonen
+git clone https://github.com/IHR-REPO/SemesterapparatsManager.git
+cd SemesterapparatsManager
+
+# Virtuelle Umgebung erstellen und Abhängigkeiten installieren
+uv sync
+
+# Anwendung starten
+uv run python main.py
+```
+
+#### Mit pip
+
+```bash
+# Repository klonen
+git clone https://github.com/IHR-REPO/SemesterapparatsManager.git
+cd SemesterapparatsManager
+
+# Virtuelle Umgebung erstellen
+python -m venv .venv
+.venv\Scripts\activate
+
+# Abhängigkeiten installieren
+pip install -e ".[dev]"
+
+# Anwendung starten
+python main.py
+```
+
+## Erster Start
+
+Beim ersten Start werden Sie aufgefordert, sich anzumelden:
+
+![Login](../images/login.png){ loading=lazy }
+
+!!! tip "Tipp"
+    Ihre Anmeldedaten werden sicher gespeichert. Bei Fragen zur Einrichtung wenden Sie sich an den Administrator.
+
+## Konfiguration
+
+Nach der Installation sollten Sie die Einstellungen überprüfen:
+
+1. Öffnen Sie das Programm
+2. Gehen Sie zu **Einstellungen** (über das Menü oder :lucide-settings:)
+3. Konfigurieren Sie:
+    - **Datenbank-Pfad**: Speicherort der SQLite-Datenbank
+    - **Zotero**: API-Schlüssel für Zitat-Funktionen
+    - **E-Mail**: SMTP-Einstellungen für Benachrichtigungen
+
+Weitere Informationen zur Konfiguration finden Sie unter [Hauptoberfläche](hauptoberflaeche.md).
--- a/docs/elsa/anlegen.md
+++ b/docs/elsa/anlegen.md
@@ -0,0 +1,86 @@
+# ELSA anlegen
+
+![ELSA Hauptoberfläche](../images/elsa_main.png){ loading=lazy }
+
+---
+
+## Neuen ELSA erstellen
+
+### Schritte
+
+1. Klicken Sie auf **Neuer Auftrag**
+2. Das Feld *Auftragsdaten* wird freigeschaltet
+3. Der Fokus wechselt automatisch auf das Feld **Prof.**
+
+### Professorenauswahl
+
+Im Feld **Prof.** werden automatisch alle bereits vorhandenen Dozenten aus den Semesterapparaten angezeigt.
+
+!!! info "Neuer Professor"
+    Wenn der Professor noch keinen Apparat hat, kann der Name manuell eingetragen werden. Es erscheinen zusätzliche Felder:
+
+![Kontaktdaten für neuen Professor](../images/new_prof_elsa_fields.png){ loading=lazy }
+
+| Feld | Beschreibung | Pflicht |
+|------|--------------|---------|
+| **Name** | Name des Dozenten | :material-check: |
+| **E-Mail** | Kontakt-E-Mail | :material-check: |
+| **Telefon** | Telefonnummer | :material-check: |
+
+!!! warning "Pflichtfelder"
+    Solange diese Felder nicht ausgefüllt sind, kann der Auftrag **nicht** gespeichert werden.
+
+---
+
+## Schnelleingabe
+
+Über das Kalender-Icon ![Kalender](../images/icon_cal.png){ .twemoji } können automatisch eingetragen werden:
+
+- [x] Aktuelles Datum
+- [x] Aktuelles Semester
+
+---
+
+## Dokumente hinzufügen
+
+![Dokumenttabelle](../images/elsa_docs.png){ loading=lazy }
+
+### Formular hinzufügen
+
+1. Klicken Sie auf **Dokument hinzufügen**
+2. Wählen Sie die Datei aus
+3. Das Dokument wird in der Datenbank gespeichert
+
+### Medien extrahieren
+
+Über **Medien aus Dokument hinzufügen** werden alle erkannten Medien automatisch in die Tabelle eingetragen.
+
+!!! tip "Abschnitte trennen"
+    Hat der Professor mehrere Abschnitte in einer Zeile gelistet, aktivieren Sie **Abschnitte trennen** – diese werden dann als separate Einträge hinzugefügt.
+
+!!! warning "Formatierung im Dokument"
+    Die Abschnitte müssen durch **Semikolon** getrennt sein:
+    
+    ```
+    1-5; 18-25; 30-35
+    ```
+
+### Automatisches Speichern
+
+Beim Klicken auf **Medien aus Dokument hinzufügen** wird der Auftrag automatisch gespeichert.
+
+---
+
+## Einträge bearbeiten
+
+Die erkannten Medien erscheinen in der Tabelle und können:
+
+- :lucide-edit: Bearbeitet werden
+- :lucide-quote: Zitiert werden → [Zum Zitieren](zitieren.md)
+- :lucide-trash: Gelöscht werden
+
+---
+
+## Dokument öffnen
+
+Über **Dokument öffnen** kann das hinzugefügte Formular jederzeit eingesehen werden.
--- a/docs/elsa/index.md
+++ b/docs/elsa/index.md
@@ -0,0 +1,46 @@
+# ELSA
+
+**ELSA** steht für **E**lektronischer **L**ehr-**S**emester**a**pparat und ermöglicht die Verwaltung digitaler Literatur für Lehrveranstaltungen.
+
+<div class="grid cards" markdown>
+
+-   :lucide-file-plus:{ .lg .middle } **ELSA anlegen**
+
+    ---
+
+    Erstellen Sie einen neuen elektronischen Semesterapparat.
+
+    [:octicons-arrow-right-24: ELSA anlegen](anlegen.md)
+
+-   :lucide-quote:{ .lg .middle } **Zitieren**
+
+    ---
+
+    Erstellen Sie automatische Zitate für Ihre digitalen Medien.
+
+    [:octicons-arrow-right-24: Zum Zitieren](zitieren.md)
+
+</div>
+
+---
+
+## Was ist ELSA?
+
+!!! abstract "Definition"
+    Ein elektronischer Semesterapparat (ELSA) ist eine digitale Sammlung von Literatur, die auf Illias bereitgestellt wird. Die Dokumente werden gescannt und mit korrekten Zitationen versehen.
+
+### Workflow
+
+```mermaid
+graph TD
+    A[ELSA anlegen] --> B[Dokumente hinzufügen]
+    B --> C[Medien aus Dokument extrahieren]
+    C --> D[Einträge zitieren]
+    D --> E[Dateien auf Illias hochladen]
+```
+
+### Voraussetzungen
+
+- [x] Konfigurierter Zotero-Account
+- [x] Eingescannte Dokumente oder Formulare
+- [x] Informationen zum Dozenten und zur Veranstaltung
--- a/docs/elsa/zitieren.md
+++ b/docs/elsa/zitieren.md
@@ -0,0 +1,95 @@
+# Zitieren
+
+Da alle gescannten Dokumente später auf **Illias** hochgeladen werden, bietet der SemesterapparatsManager eine automatische Zitierfunktion.
+
+---
+
+## Zitierstil
+
+!!! abstract "Verwendeter Stil"
+    Es wird der Zitierstil der **Deutschen Gesellschaft für Psychologie (DGPs)** verwendet.
+
+---
+
+## Oberfläche
+
+![Zitieroberfläche](../images/generate_quote_emtpy.png){ loading=lazy }
+
+### Zitat erstellen
+
+1. Wählen Sie einen Eintrag in der ELSA-Tabelle aus
+2. Klicken Sie auf **Eintrag zitieren**
+3. Der Dialog öffnet sich und sucht automatisch im Katalog
+
+!!! tip "Seitenzahlen"
+    Die angegebene Seitenzahl aus der Tabelle wird automatisch übernommen. Bei mehreren Abschnitten muss die Seitenzahl ggf. angepasst werden.
+
+---
+
+## Zitierdialog
+
+![Zitierdialog mit Ergebnis](../images/quote_search_result.png){ loading=lazy }
+
+Nach dem Öffnen werden automatisch relevante Daten aus dem Katalog abgefragt und in die Felder eingetragen.
+
+### Aktionen
+
+| Knopf | Funktion |
+|-------|----------|
+| :lucide-search: **Suchen** | Sucht im Katalog nach dem Identifikator |
+| :lucide-quote: **Zitat erstellen** | Verbindet mit Zotero und erstellt das Zitat |
+| :lucide-check: **Ok** | Schließt den Dialog |
+| :lucide-trash: **Discard** | Entfernt alle Eingaben |
+| :lucide-x: **Abbrechen** | Schließt den Dialog |
+| :lucide-rotate-ccw: **Wiederholen** | Zurück zur Eingabe für erneute Suche |
+
+---
+
+## Zitat-Erstellung
+
+```mermaid
+sequenceDiagram
+    participant U as Benutzer
+    participant S as SemesterapparatsManager
+    participant Z as Zotero
+
+    U->>S: Klick "Zitat erstellen"
+    S->>Z: Werk anlegen
+    Z-->>S: Werk-ID
+    S->>Z: Zitat abrufen
+    Z-->>S: Formatiertes Zitat
+    S->>U: Zitat anzeigen
+```
+
+### Ablauf
+
+1. Klicken Sie auf **Zitat erstellen**
+2. Eine Verbindung zu Zotero wird hergestellt
+3. Das Werk wird in Ihrer Zotero-Bibliothek angelegt
+4. Das formatierte Zitat wird zurückgegeben
+
+---
+
+## Generierte Zitate
+
+![Generierte Zitate](../images/quote_generated.png){ loading=lazy }
+
+Nach erfolgreicher Erstellung wechselt der Dialog automatisch zur Zitat-Ansicht.
+
+### Verwendung
+
+Die generierten Zitate können:
+
+- :lucide-copy: In die Zwischenablage kopiert werden
+- :lucide-file-text: Als Dateiname für das gescannte Dokument verwendet werden
+- :lucide-upload: Zusammen mit dem Dokument auf Illias hochgeladen werden
+
+---
+
+## Voraussetzungen
+
+!!! warning "Zotero-Konfiguration erforderlich"
+    Für die Zitierfunktion muss Zotero konfiguriert sein:
+    
+    1. Erstellen Sie einen API-Key in Ihrem Zotero-Account
+    2. Tragen Sie den Key in den [Einstellungen](../allgemein/hauptoberflaeche.md#zotero) ein
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,93 @@
-# ToC
+# SemesterapparatsManager

->TBD
+Willkommen zur Dokumentation des **SemesterapparatsManager**!
+
+![Hauptoberfläche](images/mainUI.png){ loading=lazy }
+
+Der SemesterapparatsManager ist ein grafisches Werkzeug zur Verwaltung von Semesterapparaten an der Pädagogischen Hochschule Freiburg. Die Anwendung ermöglicht eine benutzerfreundliche Verwaltung von physischen und digitalen Semesterapparaten.
+
+---
+
+## :lucide-rocket: Schnellstart
+
+<div class="grid cards" markdown>
+
+-   :lucide-download:{ .lg .middle } **Installation**
+
+    ---
+
+    Installieren Sie den SemesterapparatsManager in wenigen Schritten.
+
+    [:octicons-arrow-right-24: Zur Installation](allgemein/installation.md)
+
+-   :lucide-layout-dashboard:{ .lg .middle } **Hauptoberfläche**
+
+    ---
+
+    Lernen Sie die Benutzeroberfläche kennen.
+
+    [:octicons-arrow-right-24: Zur Übersicht](allgemein/hauptoberflaeche.md)
+
+-   :lucide-book-open:{ .lg .middle } **Semesterapparat anlegen**
+
+    ---
+
+    Erstellen Sie Ihren ersten Semesterapparat.
+
+    [:octicons-arrow-right-24: Zum Tutorial](semesterapparat/anlegen.md)
+
+-   :lucide-file-text:{ .lg .middle } **ELSA**
+
+    ---
+
+    Elektronische Semesterapparate verwalten.
+
+    [:octicons-arrow-right-24: Zu ELSA](elsa/anlegen.md)
+
+</div>
+
+---
+
+## :lucide-folder-tree: Dokumentationsstruktur
+
+Diese Dokumentation ist in folgende Bereiche unterteilt:
+
+| Bereich | Beschreibung |
+|---------|--------------|
+| **[Allgemein](allgemein/index.md)** | Grundlegende Informationen, Installation und Übersicht der Hauptoberfläche |
+| **[Semesterapparat](semesterapparat/index.md)** | Anlegen, Verlängern, Löschen und Suchen von Semesterapparaten |
+| **[ELSA](elsa/index.md)** | Elektronische Semesterapparate anlegen und Zitate erstellen |
+| **[Sonstiges](sonstiges/index.md)** | Zusätzliche Informationen und Bildmaterial |
+
+---
+
+## :lucide-sparkles: Features
+
+<div class="grid" markdown>
+
+!!! success "Automatisierung"
+    - Automatisches Auslesen von Antragsformularen
+    - Automatische Zitat-Erstellung via Zotero
+    - E-Mail-Benachrichtigungen an Dozenten
+
+!!! info "Verwaltung"
+    - Zentrale Datenbank für alle Apparate
+    - Statistiken und Auswertungen
+    - Such- und Filterfunktionen
+
+!!! tip "Integration"
+    - Anbindung an den Bibliothekskatalog
+    - Zotero-Integration für Zitate
+    - Mail-System für Kommunikation
+
+!!! example "Benutzerfreundlich"
+    - Intuitive grafische Oberfläche
+    - Keyboard-Shortcuts
+    - Kontextmenüs für schnellen Zugriff
+
+</div>
+
+---
+
+!!! tip "Tipp: Suche"
+    Nutzen Sie die **Suchfunktion** oben rechts ++ctrl+k++, um schnell zu den gewünschten Informationen zu gelangen.
--- a/docs/semesterapparat/anlegen.md
+++ b/docs/semesterapparat/anlegen.md
@@ -0,0 +1,143 @@
+# Semesterapparat anlegen
+
+Um einen neuen Semesterapparat anzulegen, muss zuerst der Knopf **neu. App anlegen** gedrückt werden. Das Feld der Apparatdetails wird nun zum Bearbeiten entsperrt.
+
+![Anlegen](../images/main_apparatdetails.png){ loading=lazy }
+
+---
+
+## Apparatdetails
+
+### Pflichtfelder
+
+Um einen Apparat erfolgreich anzulegen, müssen alle Felder mit einem **Sternchen (*)** ausgefüllt werden. Ist eine Eingabe nicht valide, wird neben der Eingabe ein :material-close-circle:{ style="color: red" } angezeigt.
+
+!!! warning "Formatierungsanforderungen"
+    Folgende Felder haben spezielle Formatierungsanforderungen:
+
+| Feld | Format | Beispiel |
+|------|--------|----------|
+| **Prof. Name** | Nachname, Vorname | `Müller, Hans` |
+| **Mail** | Gültige E-Mail-Adresse | `mueller@ph-freiburg.de` |
+| **Tel** | Mindestens 3 Ziffern | `0761-12345` |
+| **Semester** | Automatisch berechnet | siehe unten |
+
+### Semester-Logik
+
+Das Semester wird automatisch wie folgt berechnet:
+
+=== "Wintersemester"
+
+    - Checkbox **Winter** aktivieren
+    - **Jahr**: 
+        - Oktober–Dezember → aktuelles Jahr
+        - Januar–September → aktuelles Jahr - 1
+
+=== "Sommersemester"
+
+    - Checkbox **Sommer** aktivieren
+    - **Jahr**: aktuelles Jahr (März–August)
+
+### Fehlermeldungen
+
+Beim Versuch, den Apparat zu speichern, bevor alle Felder korrekt ausgefüllt sind, erscheint eine Fehlermeldung:
+
+![Fehler](../images/main_apparatdetails_error.png){ loading=lazy }
+
+!!! tip "Tipp"
+    Über **Ok** oder **Cancel** wird die Meldung geschlossen und der Apparat kann weiter bearbeitet werden.
+
+---
+
+## Dokumente hinzufügen
+
+Dem Apparat können Dokumente hinzugefügt werden. Besonders hilfreich ist das Hinzufügen der **Antragsformulare**, da der SemesterapparatsManager diese automatisch auslesen kann.
+
+```mermaid
+graph LR
+    A[Dokument hinzufügen] --> B{Antragsformular?}
+    B -->|Ja| C[Medien aus Dokument hinzufügen]
+    B -->|Nein| D[Als Referenz speichern]
+    C --> E[Medien werden automatisch erkannt]
+```
+
+1. Klicken Sie auf **Dokumente hinzufügen**
+2. Wählen Sie die gewünschte(n) Datei(en) aus
+3. Bei Antragsformularen: Klicken Sie auf **Medien aus Dokument hinzufügen**
+
+!!! warning "Wichtig: Automatisches Speichern"
+    Beim Klicken auf **Medien aus Dokument hinzufügen** wird der Apparat automatisch gespeichert. Dies ist erforderlich, da Medien nur einem existierenden Apparat hinzugefügt werden können.
+
+---
+
+## Medienliste
+
+![Optionen der Medienliste](../images/medialist_options.png){ loading=lazy }
+
+In der Medienliste werden alle dem Apparat zugeordneten Medien angezeigt.
+
+### Optionen
+
+| Option | Beschreibung |
+|--------|--------------|
+| :lucide-eye: **gel. Medien anzeigen** | Zeigt auch gelöschte Medien an |
+| :lucide-check-circle: **im Apparat?** | Prüft, ob ausgewählte Medien dem Apparat hinzugefügt wurden |
+| :lucide-plus: **Medien hinzufügen** | Manuelle Eingabe von Signaturen |
+
+### Kontextmenü
+
+Mit einem **Rechtsklick** auf ein Medium öffnet sich das Kontextmenü:
+
+![Kontextmenü](../images/media_context_menu_root.png){ loading=lazy }
+
+=== "Allgemeines"
+
+    ![Kontextmenü Allgemeines](../images/media_context_menu_general.png){ loading=lazy }
+
+    - **Bearbeiten**: Metadaten einsehen/bearbeiten
+    - **Löschen**: Medium aus dem Apparat entfernen (nicht physisch löschen)
+
+=== "Apparate"
+
+    ![Kontextmenü Apparate](../images/media_context_menu_apparats.png){ loading=lazy }
+
+    - **Zum Apparat hinzufügen**: *(derzeit deaktiviert)*
+    - **In Apparat verschieben**: Medium in anderen Apparat verschieben
+    - **In Apparat kopieren**: Medium in anderen Apparat kopieren
+
+!!! tip "Mehrfachauswahl"
+    Mit ++ctrl+left-button++ können mehrere Medien ausgewählt werden.
+
+---
+
+## Medien manuell hinzufügen
+
+![Medien hinzufügen](../images/add_media.png){ loading=lazy }
+
+### Eingabe
+
+Geben Sie jede Signatur in eine neue Zeile ein und bestätigen Sie mit ++enter++.
+
+### Optionen
+
+| Option | Beschreibung |
+|--------|--------------|
+| **Modus** | Wählt die Metadatenquelle |
+| **Jedes Buch verwenden** | Erlaubt das Hinzufügen von Medien, die noch nicht im Apparat sind |
+| **Exakte Signatur** | Nur diese spezifische Signatur verwenden (kein alternatives Exemplar) |
+
+!!! info "Signatursuche"
+    Ohne **Exakte Signatur** wird nach der ähnlichsten Signatur gesucht – das gefundene Buch ist dasselbe, aber möglicherweise ein anderes Exemplar.
+
+---
+
+## Apparat speichern
+
+Nach dem Ausfüllen aller Pflichtfelder:
+
+1. Klicken Sie auf **Speichern**
+2. Der Apparat wird in der Datenbank gespeichert
+3. Optional: Bei aktiviertem **Mail senden** öffnet sich der Mail-Dialog
+
+!!! note "E-Mail-Versand"
+    Der E-Mail-Versand erfordert konfigurierte [Mail-Zugangsdaten](../allgemein/hauptoberflaeche.md#e-mail).
--- a/docs/semesterapparat/index.md
+++ b/docs/semesterapparat/index.md
@@ -0,0 +1,47 @@
+# Semesterapparat
+
+In diesem Abschnitt finden Sie alle Informationen zur Verwaltung von Semesterapparaten.
+
+<div class="grid cards" markdown>
+
+-   :lucide-book-plus:{ .lg .middle } **Anlegen**
+
+    ---
+
+    Erstellen Sie neue Semesterapparate mit allen erforderlichen Informationen.
+
+    [:octicons-arrow-right-24: Apparat anlegen](anlegen.md)
+
+-   :lucide-calendar-plus:{ .lg .middle } **Verlängern**
+
+    ---
+
+    Verlängern Sie bestehende Apparate für ein weiteres Semester.
+
+    [:octicons-arrow-right-24: Apparat verlängern](verlaengern.md)
+
+-   :lucide-trash-2:{ .lg .middle } **Löschen**
+
+    ---
+
+    Entfernen Sie nicht mehr benötigte Semesterapparate.
+
+    [:octicons-arrow-right-24: Apparat löschen](loeschen.md)
+
+-   :lucide-bar-chart-2:{ .lg .middle } **Statistik**
+
+    ---
+
+    Erhalten Sie Einblicke in die Nutzung der Semesterapparate.
+
+    [:octicons-arrow-right-24: Zur Statistik](statistik.md)
+
+-   :lucide-search:{ .lg .middle } **Suche**
+
+    ---
+
+    Durchsuchen Sie bestehende Apparate und Medien.
+
+    [:octicons-arrow-right-24: Zur Suche](suche.md)
+
+</div>
--- a/docs/semesterapparat/loeschen.md
+++ b/docs/semesterapparat/loeschen.md
@@ -0,0 +1,63 @@
+# Semesterapparat löschen
+
+Das Löschen von Semesterapparaten erfolgt über die [Suche & Statistik](suche.md) Seite.
+
+---
+
+## Löschvorgang
+
+### Einzelnen Apparat löschen
+
+1. Navigieren Sie zu **Suchen/Statistik**
+2. Suchen Sie den gewünschten Apparat
+3. Aktivieren Sie die Checkbox des Apparats
+4. Klicken Sie auf **Ausgewählte Löschen**
+
+### Mehrere Apparate löschen
+
+1. Verwenden Sie die Suche mit dem Filter **Löschbar**
+2. Wählen Sie alle zu löschenden Apparate aus
+3. Klicken Sie auf **Ausgewählte Löschen**
+
+!!! tip "Filter: Löschbar"
+    Der Filter **Löschbar** zeigt alle Apparate an, deren Endsemester abgelaufen ist und die zur Löschung vorgemerkt werden können.
+
+---
+
+## Bestätigung
+
+Nach dem Klicken auf **Ausgewählte Löschen**:
+
+![Löschbestätigung](../images/ss_stat_delete.png){ loading=lazy }
+
+Die gelöschten Apparate werden in der Tabelle mit **rotem Hintergrund** angezeigt.
+
+!!! failure "Gelöschte Apparate"
+    Gelöschte Apparate verbleiben in der Datenbank, werden aber als inaktiv markiert. Sie können bei Bedarf wiederhergestellt werden.
+
+---
+
+## Dozenten benachrichtigen
+
+Bei der Löschung kann eine Benachrichtigung an den Dozenten versendet werden:
+
+![Mail bei Löschung](../images/mail_delete.png){ loading=lazy }
+
+1. Wählen Sie die zu löschenden Apparate aus
+2. Klicken Sie auf **Ausgewählte Benachrichtigen**
+3. Konfigurieren Sie die Anrede
+4. Versenden Sie die Mail
+
+Weitere Informationen: [Mails](../allgemein/hauptoberflaeche.md#e-mail)
+
+---
+
+## Wiederherstellen
+
+Gelöschte Apparate können wiederhergestellt werden:
+
+1. Suchen Sie den gelöschten Apparat (rot markiert)
+2. Rechtsklick → **Wiederherstellen**
+
+!!! success "Mehrfachwiederherstellung"
+    Mit ++ctrl+left-button++ können mehrere Apparate gleichzeitig ausgewählt und wiederhergestellt werden.
--- a/docs/semesterapparat/statistik.md
+++ b/docs/semesterapparat/statistik.md
@@ -0,0 +1,86 @@
+# Statistik
+
+Die Statistikfunktion bietet einen Überblick über alle Semesterapparate und deren Entwicklung über die Zeit.
+
+![Statistikbereich](../images/ss_stats_table.png){ loading=lazy }
+
+---
+
+## Apparatsstatistik
+
+Die Statistik zeigt alle Semester an, in denen Apparate erstellt oder gelöscht wurden.
+
+### Tabellenansicht
+
+| Spalte | Beschreibung |
+|--------|--------------|
+| **Semester** | Das betroffene Semester |
+| **Erstellt** | Anzahl erstellter Apparate |
+| **Gelöscht** | Anzahl gelöschter Apparate |
+
+!!! tip "Detailansicht"
+    Mit einem **Doppelklick** auf ein Semester werden die einzelnen Apparate angezeigt.
+
+### Detaillierte Ansicht
+
+![Detailansicht](../images/ss_stats_detailed.png){ loading=lazy }
+
+Die Detailansicht zeigt:
+
+- Alle Personen, die in diesem Semester Apparate erstellt/gelöscht haben
+- Pro Person: Liste aller erstellten oder gelöschten Apparate
+
+??? info "Navigation"
+    - Klick auf :material-chevron-right: zeigt die Apparate einer Person
+    - Doppelklick auf einen Apparat wechselt zur [Hauptoberfläche](../allgemein/hauptoberflaeche.md)
+
+!!! warning "Gelöschte Apparate"
+    Gelöschte Apparate können nicht angezeigt werden – die Doppelklick-Funktion ist dort deaktiviert.
+
+---
+
+## Diagramm
+
+![Statistik-Diagramm](../images/ss_stats_graph.png){ loading=lazy }
+
+Das Liniendiagramm visualisiert:
+
+- :material-chart-line:{ style="color: green" } **Grün**: Erstellte Apparate
+- :material-chart-line:{ style="color: red" } **Rot**: Gelöschte Apparate
+
+!!! tip "Interaktivität"
+    Hovern Sie über Datenpunkte für genaue Werte.
+
+---
+
+## Auswertungen
+
+### Typische Fragestellungen
+
+<div class="grid cards" markdown>
+
+-   :lucide-trending-up: **Wachstum**
+
+    ---
+
+    Wie viele Apparate wurden pro Semester erstellt?
+
+-   :lucide-users: **Nutzung**
+
+    ---
+
+    Welche Dozenten nutzen den Service am meisten?
+
+-   :lucide-calendar: **Saisonalität**
+
+    ---
+
+    Gibt es Unterschiede zwischen Sommer- und Wintersemester?
+
+-   :lucide-archive: **Bereinigung**
+
+    ---
+
+    Wie viele Apparate werden regelmäßig gelöscht?
+
+</div>
--- a/docs/semesterapparat/suche.md
+++ b/docs/semesterapparat/suche.md
@@ -0,0 +1,109 @@
+# Suche
+
+![Suche und Statistik](../images/main_search_stat.png){ loading=lazy }
+
+Die Suchseite bietet zwei Hauptfunktionen: die **Apparatsuche** und die **Mediensuche**.
+
+---
+
+## Apparatsuche
+
+### Suchfilter
+
+![Statistiksuche](../images/ss_stat_search.png){ loading=lazy }
+
+| Filter | Beschreibung |
+|--------|--------------|
+| **AppNr** | Nummer des Semesterapparates (Dropdown mit allen belegten Nummern) |
+| **Person** | Name des Dozenten |
+| **Fach** | Fachrichtung des Apparates |
+| **Erstell-Semester** | Semester der Erstellung |
+| **End-Semester** | Geplantes Ende des Apparates |
+| **Dauerapp** | Nur Dauerapparate anzeigen |
+| **Löschbar** | Alle löschbaren Apparate (überschreibt andere Filter) |
+
+!!! tip "Alle anzeigen"
+    Starten Sie die Suche ohne Eingabe, um **alle** Semesterapparate anzuzeigen.
+
+---
+
+## Suchergebnisse
+
+![Suchergebnisse](../images/ss_stat_result.png){ loading=lazy }
+
+### Ergebnistabelle
+
+Für jeden Treffer wird angezeigt:
+
+- :material-checkbox-marked-outline: Checkbox zur Auswahl
+- **Apparatsname**
+- **Apparatsnummer**
+- **Person**
+- **Fach**
+
+!!! failure "Gelöschte Apparate"
+    Gelöschte Apparate werden mit **rotem Hintergrund** angezeigt.
+
+### Slider
+
+!!! info "Layout anpassen"
+    Der vertikale Slider zwischen Tabelle und Graph kann verschoben werden, um mehr Platz für einen der Bereiche zu schaffen.
+
+---
+
+## Aktionen
+
+### Ausgewählte Löschen
+
+![Löschen](../images/ss_stat_delete.png){ loading=lazy }
+
+1. Aktivieren Sie die Checkboxen der zu löschenden Apparate
+2. Klicken Sie auf **Ausgewählte Löschen**
+3. Gelöschte Apparate werden rot markiert
+
+Weitere Informationen: [Apparat löschen](loeschen.md)
+
+### Ausgewählte Benachrichtigen
+
+![Mail bei Löschung](../images/mail_delete.png){ loading=lazy }
+
+Versendet eine E-Mail an die Dozenten der ausgewählten Apparate.
+
+1. Wählen Sie die Apparate aus
+2. Klicken Sie auf **Ausgewählte Benachrichtigen**
+3. Konfigurieren Sie die Anrede
+4. Versenden Sie die Mail
+
+---
+
+## Kontextmenü
+
+Rechtsklick auf einen Apparat öffnet das Kontextmenü:
+
+| Option | Beschreibung |
+|--------|--------------|
+| :lucide-calendar-plus: **Verlängern** | Öffnet den [Verlängerungsdialog](verlaengern.md) |
+| :lucide-undo: **Wiederherstellen** | Stellt gelöschte Apparate wieder her |
+
+!!! tip "Mehrfachauswahl"
+    Mit ++ctrl+left-button++ auf die Zeilennummer können mehrere Apparate für die Wiederherstellung ausgewählt werden.
+
+---
+
+## Mediensuche
+
+Der **Suchbereich** prüft, ob ein Exemplar in einem Apparat vorhanden ist.
+
+### Suchkriterien
+
+| Kriterium | Beschreibung |
+|-----------|--------------|
+| **Titel** | Titel des Exemplars (automatische Trunkierung) |
+| **Signatur** | Signatur des Exemplars (automatische Trunkierung) |
+
+!!! warning "Pflichtfelder"
+    Im Gegensatz zur Apparatsuche kann hier **keine** leere Suche durchgeführt werden, da zu viele Ergebnisse möglich wären.
+
+### Ergebnisse
+
+Die gefundenen Exemplare werden mit den zugehörigen Apparaten angezeigt.
--- a/docs/semesterapparat/verlaengern.md
+++ b/docs/semesterapparat/verlaengern.md
@@ -0,0 +1,44 @@
+# Semesterapparat verlängern
+
+Ein Dialog zum Verlängern eines Semesterapparates für ein weiteres Semester.
+
+![Verlängerung](../images/extend.png){ loading=lazy }
+
+---
+
+## Verlängerung durchführen
+
+### Schritte
+
+1. Wählen Sie den zu verlängernden Apparat in der [Suche](suche.md) oder [Statistik](statistik.md) aus
+2. Öffnen Sie den Verlängerungsdialog via Rechtsklick → **Verlängern**
+3. Wählen Sie das Zielsemester aus
+4. Klicken Sie auf **Speichern**
+
+### Eingabefelder
+
+| Feld | Beschreibung |
+|------|--------------|
+| **Semester** | Sommer- oder Wintersemester auswählen |
+| **Jahr** | Das Jahr des neuen Semesters |
+| **Dauerapparat** | :lucide-check: Markiert den Apparat als Dauerapparat |
+
+---
+
+## Dauerapparat
+
+!!! info "Was ist ein Dauerapparat?"
+    Ein Dauerapparat wird nicht automatisch zur Löschung vorgemerkt und bleibt aktiv, bis er manuell gelöscht wird.
+
+!!! warning "Hinweis"
+    Damit der Apparat als Dauerapparat verlängert werden kann, **muss** trotzdem ein Semester angegeben werden.
+
+---
+
+## Nach der Verlängerung
+
+Nach dem Speichern:
+
+- [x] Das Endsemester wird automatisch aktualisiert
+- [x] Die Änderung erscheint in allen relevanten Tabellen
+- [x] Optional: Benachrichtigung an den Dozenten versenden
--- a/docs/sonstiges/bilder.md
+++ b/docs/sonstiges/bilder.md
@@ -0,0 +1,51 @@
+# Bilder
+
+Eine Sammlung von Screenshots und Referenzbildern aus dem SemesterapparatsManager.
+
+---
+
+## Admin-Bereich
+
+### Admin-Aktionen
+
+![Admin Aktionen](../images/actions.png){ loading=lazy }
+
+Die Admin-Aktionen ermöglichen administrative Aufgaben wie Datenbankwartung und Systemkonfiguration.
+
+---
+
+## Semesterapparat
+
+### Apparatscheckliste
+
+![Checkliste](../images/checklist.png){ loading=lazy }
+
+Die Checkliste zeigt den aktuellen Status eines Semesterapparates an.
+
+### Medien hinzufügen
+
+![Medien hinzufügen](../images/add_media.png){ loading=lazy }
+
+Dialog zum manuellen Hinzufügen von Medien über ihre Signaturen.
+
+---
+
+## Eingabehilfen
+
+### Kalender
+
+![Kalender](../images/calendar.png){ loading=lazy }
+
+Der Kalender ermöglicht die schnelle Auswahl von Datum und Semester.
+
+---
+
+## Weitere Screenshots
+
+!!! tip "Screenshots in der Dokumentation"
+    Detaillierte Screenshots finden Sie in den jeweiligen Abschnitten:
+    
+    - [Hauptoberfläche](../allgemein/hauptoberflaeche.md) – Übersicht der Benutzeroberfläche
+    - [Semesterapparat anlegen](../semesterapparat/anlegen.md) – Erstellung von Apparaten
+    - [ELSA anlegen](../elsa/anlegen.md) – Elektronische Semesterapparate
+    - [Zitieren](../elsa/zitieren.md) – Zitat-Dialog
--- a/docs/sonstiges/index.md
+++ b/docs/sonstiges/index.md
@@ -0,0 +1,15 @@
+# Sonstiges
+
+Zusätzliche Informationen und Ressourcen zum SemesterapparatsManager.
+
+<div class="grid cards" markdown>
+
+-   :lucide-image:{ .lg .middle } **Bilder**
+
+    ---
+
+    Bildergalerie mit Screenshots und Referenzbildern.
+
+    [:octicons-arrow-right-24: Zur Galerie](bilder.md)
+
+</div>