diff --git a/.gitea/workflows/docs.yml b/.gitea/workflows/docs.yml new file mode 100644 index 0000000..ec0e85b --- /dev/null +++ b/.gitea/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Documentation +on: + push: + branches: + - master + - main +permissions: + contents: read + pages: write + id-token: write +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/configure-pages@v5 + - uses: actions/checkout@v5 + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: pip install zensical + - run: zensical build --clean + - uses: actions/upload-pages-artifact@v4 + with: + path: site + - uses: actions/deploy-pages@v4 diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index 7b84059..741c6d0 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -40,7 +40,7 @@ jobs: fetch-tags: true - name: Install uv - uses: astral-sh/setup-uv@v5 + uses: astral-sh/setup-uv@v7 - name: Set up Python uses: actions/setup-python@v5 @@ -97,7 +97,7 @@ jobs: fetch-tags: true - name: Install uv - uses: astral-sh/setup-uv@v5 + uses: astral-sh/setup-uv@v7 - name: Set up Python uses: actions/setup-python@v5 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a290858 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,7 @@ +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.6.9 # latest ruff version + hooks: + - id: ruff + args: ["--fix"] + - id: ruff-format diff --git a/docs/admin.md b/docs/admin.md deleted file mode 100644 index bd3b512..0000000 --- a/docs/admin.md +++ /dev/null @@ -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. diff --git a/docs/allgemein/hauptoberflaeche.md b/docs/allgemein/hauptoberflaeche.md new file mode 100644 index 0000000..ecfcd31 --- /dev/null +++ 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 + +
+ +- :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) + +
+ +--- + +## Ü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. diff --git a/docs/allgemein/index.md b/docs/allgemein/index.md new file mode 100644 index 0000000..1eafdfb --- /dev/null +++ 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. + +
+ +- :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) + +
diff --git a/docs/allgemein/info.md b/docs/allgemein/info.md new file mode 100644 index 0000000..c26fca0 --- /dev/null +++ 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: + +
+ +- :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. + +
+ +## 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. diff --git a/docs/allgemein/installation.md b/docs/allgemein/installation.md new file mode 100644 index 0000000..e044b2b --- /dev/null +++ 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). diff --git a/docs/elsa/anlegen.md b/docs/elsa/anlegen.md new file mode 100644 index 0000000..f24ec9f --- /dev/null +++ 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. diff --git a/docs/elsa/index.md b/docs/elsa/index.md new file mode 100644 index 0000000..b3947a3 --- /dev/null +++ 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. + +
+ +- :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) + +
+ +--- + +## 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 diff --git a/docs/elsa/zitieren.md b/docs/elsa/zitieren.md new file mode 100644 index 0000000..6e48485 --- /dev/null +++ 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 diff --git a/docs/index.md b/docs/index.md index 8f43754..0e766af 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,93 @@ -# ToC +# SemesterapparatsManager ->TBD \ No newline at end of file +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 + +
+ +- :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) + +
+ +--- + +## :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 + +
+ +!!! 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 + +
+ +--- + +!!! tip "Tipp: Suche" + Nutzen Sie die **Suchfunktion** oben rechts ++ctrl+k++, um schnell zu den gewünschten Informationen zu gelangen. diff --git a/docs/semesterapparat/anlegen.md b/docs/semesterapparat/anlegen.md new file mode 100644 index 0000000..9504c4a --- /dev/null +++ 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). diff --git a/docs/semesterapparat/index.md b/docs/semesterapparat/index.md new file mode 100644 index 0000000..50622c8 --- /dev/null +++ b/docs/semesterapparat/index.md @@ -0,0 +1,47 @@ +# Semesterapparat + +In diesem Abschnitt finden Sie alle Informationen zur Verwaltung von Semesterapparaten. + +
+ +- :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) + +
diff --git a/docs/semesterapparat/loeschen.md b/docs/semesterapparat/loeschen.md new file mode 100644 index 0000000..fbabd9e --- /dev/null +++ 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. diff --git a/docs/semesterapparat/statistik.md b/docs/semesterapparat/statistik.md new file mode 100644 index 0000000..b072b10 --- /dev/null +++ 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 + +
+ +- :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? + +
diff --git a/docs/semesterapparat/suche.md b/docs/semesterapparat/suche.md new file mode 100644 index 0000000..cb9ebc5 --- /dev/null +++ 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. diff --git a/docs/semesterapparat/verlaengern.md b/docs/semesterapparat/verlaengern.md new file mode 100644 index 0000000..9624a2f --- /dev/null +++ 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 diff --git a/docs/sonstiges/bilder.md b/docs/sonstiges/bilder.md new file mode 100644 index 0000000..45a5f00 --- /dev/null +++ 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 diff --git a/docs/sonstiges/index.md b/docs/sonstiges/index.md new file mode 100644 index 0000000..96f1758 --- /dev/null +++ b/docs/sonstiges/index.md @@ -0,0 +1,15 @@ +# Sonstiges + +Zusätzliche Informationen und Ressourcen zum SemesterapparatsManager. + +
+ +- :lucide-image:{ .lg .middle } **Bilder** + + --- + + Bildergalerie mit Screenshots und Referenzbildern. + + [:octicons-arrow-right-24: Zur Galerie](bilder.md) + +
diff --git a/pyproject.toml b/pyproject.toml index 943090d..1fbc4c1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,9 +14,6 @@ dependencies = [ "docx2pdf>=0.1.8", "httpx>=0.28.1", "loguru>=0.7.3", - "mkdocs>=1.6.1", - "mkdocs-material>=9.5.49", - "mkdocs-material-extensions>=1.3.1", "natsort>=8.4.0", "omegaconf>=2.3.0", "openai>=1.79.0", @@ -31,6 +28,7 @@ dependencies = [ "ratelimit>=2.2.1", "regex>=2025.11.3", "requests>=2.32.3", + "zensical>=0.0.10", ] [dependency-groups] diff --git a/zensical.toml b/zensical.toml new file mode 100644 index 0000000..bee46f0 --- /dev/null +++ b/zensical.toml @@ -0,0 +1,332 @@ +# ============================================================================ +# +# The configuration produced by default is meant to highlight the features +# that Zensical provides and to serve as a starting point for your own +# projects. +# +# ============================================================================ + +[project] + +# The docs_dir is the directory containing the documentation source files. +# Read more: https://zensical.org/docs/setup/basics/#docs_dir +docs_dir = "docs" + +# The site_name is shown in the page header and the browser window title +# +# Read more: https://zensical.org/docs/setup/basics/#site_name +site_name = "SemesterapparatsManager" + +# The site_description is included in the HTML head and should contain a +# meaningful description of the site content for use by search engines. +# +# Read more: https://zensical.org/docs/setup/basics/#site_description +site_description = "Dokumentation für den SemesterapparatsManager" + +# The site_author attribute. This is used in the HTML head element. +# +# Read more: https://zensical.org/docs/setup/basics/#site_author +site_author = "Alexander Kirchner" + +# The site_url is the canonical URL for your site. When building online +# documentation you should set this. +# Read more: https://zensical.org/docs/setup/basics/#site_url +#site_url = "https://www.example.com/" + +# The copyright notice appears in the page footer and can contain an HTML +# fragment. +# +# Read more: https://zensical.org/docs/setup/basics/#copyright +copyright = """ +Copyright © 2025 Alexander Kirchner +""" + +# Zensical supports both implicit navigation and explicitly defined navigation. +# If you decide not to define a navigation here then Zensical will simply +# derive the navigation structure from the directory structure of your +# "docs_dir". The definition below demonstrates how a navigation structure +# can be defined using TOML syntax. +# +# Read more: https://zensical.org/docs/setup/navigation/ +nav = [ + { "Startseite" = "index.md" }, + { "Allgemein" = [ + { "Übersicht" = "allgemein/index.md" }, + { "Info" = "allgemein/info.md" }, + { "Installation" = "allgemein/installation.md" }, + { "Hauptoberfläche" = "allgemein/hauptoberflaeche.md" }, + ] }, + { "Semesterapparat" = [ + { "Übersicht" = "semesterapparat/index.md" }, + { "Anlegen" = "semesterapparat/anlegen.md" }, + { "Verlängern" = "semesterapparat/verlaengern.md" }, + { "Löschen" = "semesterapparat/loeschen.md" }, + { "Statistik" = "semesterapparat/statistik.md" }, + { "Suche" = "semesterapparat/suche.md" }, + ] }, + { "ELSA" = [ + { "Übersicht" = "elsa/index.md" }, + { "Anlegen" = "elsa/anlegen.md" }, + { "Zitieren" = "elsa/zitieren.md" }, + ] }, + { "Sonstiges" = [ + { "Übersicht" = "sonstiges/index.md" }, + { "Bilder" = "sonstiges/bilder.md" }, + ] }, +] + +# With the "extra_css" option you can add your own CSS styling to customize +# your Zensical project according to your needs. You can add any number of +# CSS files. +# +# The path provided should be relative to the "docs_dir". +# +# Read more: https://zensical.org/docs/customization/#additional-css +# +#extra_css = ["assets/stylesheets/extra.css"] + +# With the `extra_javascript` option you can add your own JavaScript to your +# project to customize the behavior according to your needs. +# +# The path provided should be relative to the "docs_dir". +# +# Read more: https://zensical.org/docs/customization/#additional-javascript +#extra_javascript = ["assets/javascript/extra.js"] + +# ---------------------------------------------------------------------------- +# Section for configuring theme options +# ---------------------------------------------------------------------------- +[project.theme] + +# change this to "classic" to use the traditional Material for MkDocs look. +#variant = "classic" + +# Zensical allows you to override specific blocks, partials, or whole +# templates as well as to define your own templates. To do this, uncomment +# the custom_dir setting below and set it to a directory in which you +# keep your template overrides. +# +# Read more: +# - https://zensical.org/docs/customization/#extending-the-theme +# +#custom_dir = "overrides" + +# With the "favicon" option you can set your own image to use as the icon +# browsers will use in the browser title bar or tab bar. The path provided +# must be relative to the "docs_dir". +# +# Read more: +# - https://zensical.org/docs/setup/logo-and-icons/#favicon +# - https://developer.mozilla.org/en-US/docs/Glossary/Favicon +# +#favicon = "assets/images/favicon.png" + +# Zensical supports more than 60 different languages. This means that the +# labels and tooltips that Zensical's templates produce are translated. +# The "language" option allows you to set the language used. This language +# is also indicated in the HTML head element to help with accessibility +# and guide search engines and translation tools. +# +# The default language is "en" (English). It is possible to create +# sites with multiple languages and configure a language selector. See +# the documentation for details. +# +# Read more: +# - https://zensical.org/docs/setup/language/ +# +language = "de" + +# Zensical provides a number of feature toggles that change the behavior +# of the documentation site. +features = [ + # Zensical includes an announcement bar. This feature allows users to + # dismiss it then they have read the announcement. + # https://zensical.org/docs/setup/header/#announcement-bar + "announce.dismiss", + "search.suggest", + "search.highlight", + + # If you have a repository configured and turn feature this on, Zensical + # will generate an edit button for the page. This works for common + # repository hosting services. + # https://zensical.org/docs/setup/repository/#code-actions + #"content.action.edit", + + # If you have a repository configured and turn feature this on, Zensical + # will generate a button that allows the user to view the Markdown + # code for the current page. + # https://zensical.org/docs/setup/repository/#code-actions + #"content.action.view", + + # Code annotations allow you to add an icon with a tooltip to your + # code blocks to provide explanations at crucial points. + # https://zensical.org/docs/authoring/code-blocks/#code-annotations + "content.code.annotate", + + # This feature turns on a button in code blocks that allow users to + # copy the content to their clipboard without first selecting it. + # https://zensical.org/docs/authoring/code-blocks/#code-copy-button + "content.code.copy", + + # Code blocks can include a button to allow for the selection of line + # ranges by the user. + # https://zensical.org/docs/authoring/code-blocks/#code-selection-button + "content.code.select", + + # Zensical can render footnotes as inline tooltips, so the user can read + # the footnote without leaving the context of the document. + # https://zensical.org/docs/authoring/footnotes/#footnote-tooltips + "content.footnote.tooltips", + + # If you have many content tabs that have the same titles (e.g., "Python", + # "JavaScript", "Cobol"), this feature causes all of them to switch to + # at the same time when the user chooses their language in one. + # https://zensical.org/docs/authoring/content-tabs/#linked-content-tabs + "content.tabs.link", + + # TODO: not sure I understand this one? Is there a demo of this in the docs? + # https://zensical.org/docs/authoring/tooltips/#improved-tooltips + "content.tooltips", + + # With this feature enabled, Zensical will automatically hide parts + # of the header when the user scrolls past a certain point. + # https://zensical.org/docs/setup/header/#automatic-hiding + # "header.autohide", + + # Turn on this feature to expand all collapsible sections in the + # navigation sidebar by default. + # https://zensical.org/docs/setup/navigation/#navigation-expansion + # "navigation.expand", + + # This feature turns on navigation elements in the footer that allow the + # user to navigate to a next or previous page. + # https://zensical.org/docs/setup/footer/#navigation + "navigation.footer", + + # When section index pages are enabled, documents can be directly attached + # to sections, which is particularly useful for providing overview pages. + # https://zensical.org/docs/setup/navigation/#section-index-pages + "navigation.indexes", + + # When instant navigation is enabled, clicks on all internal links will be + # intercepted and dispatched via XHR without fully reloading the page. + # https://zensical.org/docs/setup/navigation/#instant-navigation + "navigation.instant", + + # With instant prefetching, your site will start to fetch a page once the + # user hovers over a link. This will reduce the perceived loading time + # for the user. + # https://zensical.org/docs/setup/navigation/#instant-prefetching + "navigation.instant.prefetch", + + # In order to provide a better user experience on slow connections when + # using instant navigation, a progress indicator can be enabled. + # https://zensical.org/docs/setup/navigation/#progress-indicator + #"navigation.instant.progress", + + # When navigation paths are activated, a breadcrumb navigation is rendered + # above the title of each page + # https://zensical.org/docs/setup/navigation/#navigation-path + "navigation.path", + + # When pruning is enabled, only the visible navigation items are included + # in the rendered HTML, reducing the size of the built site by 33% or more. + # https://zensical.org/docs/setup/navigation/#navigation-pruning + #"navigation.prune", + + # When sections are enabled, top-level sections are rendered as groups in + # the sidebar for viewports above 1220px, but remain as-is on mobile. + # https://zensical.org/docs/setup/navigation/#navigation-sections + "navigation.sections", + + # When tabs are enabled, top-level sections are rendered in a menu layer + # below the header for viewports above 1220px, but remain as-is on mobile. + # https://zensical.org/docs/setup/navigation/#navigation-tabs + #"navigation.tabs", + + # When sticky tabs are enabled, navigation tabs will lock below the header + # and always remain visible when scrolling down. + # https://zensical.org/docs/setup/navigation/#sticky-navigation-tabs + #"navigation.tabs.sticky", + + # A back-to-top button can be shown when the user, after scrolling down, + # starts to scroll up again. + # https://zensical.org/docs/setup/navigation/#back-to-top-button + "navigation.top", + + # When anchor tracking is enabled, the URL in the address bar is + # automatically updated with the active anchor as highlighted in the table + # of contents. + # https://zensical.org/docs/setup/navigation/#anchor-tracking + "navigation.tracking", + + # When search highlighting is enabled and a user clicks on a search result, + # Zensical will highlight all occurrences after following the link. + # https://zensical.org/docs/setup/search/#search-highlighting + "search.highlight", + + # When anchor following for the table of contents is enabled, the sidebar + # is automatically scrolled so that the active anchor is always visible. + # https://zensical.org/docs/setup/navigation/#anchor-following + # "toc.follow", + + # When navigation integration for the table of contents is enabled, it is + # always rendered as part of the navigation sidebar on the left. + # https://zensical.org/docs/setup/navigation/#navigation-integration + #"toc.integrate", +] + +# ---------------------------------------------------------------------------- +# In the "palette" subsection you can configure options for the color scheme. +# You can configure different color # schemes, e.g., to turn on dark mode, +# that the user can switch between. Each color scheme can be further +# customized. +# +# Read more: +# - https://zensical.org/docs/setup/colors/ +# ---------------------------------------------------------------------------- +[[project.theme.palette]] +scheme = "default" +toggle.icon = "lucide/sun" +toggle.name = "Switch to dark mode" + +[[project.theme.palette]] +scheme = "slate" +toggle.icon = "lucide/moon" +toggle.name = "Switch to light mode" + +# ---------------------------------------------------------------------------- +# In the "font" subsection you can configure the fonts used. By default, fonts +# are loaded from Google Fonts, giving you a wide range of choices from a set +# of suitably licensed fonts. There are options for a normal text font and for +# a monospaced font used in code blocks. +# ---------------------------------------------------------------------------- +#[project.theme.font] +#text = "Inter" +#code = "Jetbrains Mono" + +# ---------------------------------------------------------------------------- +# You can configure your own logo to be shown in the header using the "logo" +# option in the "icons" subsection. The logo can be a path to a file in your +# "docs_dir" or it can be a path to an icon. +# +# Likewise, you can customize the logo used for the repository section of the +# header. Zensical derives the default logo for this from the repository URL. +# See below... +# +# There are other icons you can customize. See the documentation for details. +# +# Read more: +# - https://zensical.org/docs/setup/logo-and-icons +# - https://zensical.org/docs/authoring/icons-emojis/#search +# ---------------------------------------------------------------------------- +#[project.theme.icon] +#logo = "lucide/smile" +#repo = "lucide/smile" + +# ---------------------------------------------------------------------------- +# The "extra" section contains miscellaneous settings. +# ---------------------------------------------------------------------------- +#[[project.extra.social]] +#icon = "fontawesome/brands/github" +#link = "https://github.com/user/repo"