init

ai-context/strukturelle-vorgaben.md

@@ -0,0 +1,131 @@
+# Strukturelle Vorgaben – Quellcode-Konventionen
+
+Dieses Dokument legt verbindliche Konventionen für alle Quelldateien im Projekt fest.
+
+---
+
+## 1. Datei-Header
+
+Jede Quelldatei beginnt mit einem standardisierten Header. Der Header dient gleichzeitig als Modul-Docstring und wird von **Sphinx** zur automatischen Dokumentationserzeugung ausgewertet (Python-Äquivalent zu JavaDoc).
+
+### Python (`.py`)
+
+Der Header ist ein Modul-Docstring (triple-quoted) direkt am Dateianfang. Sphinx liest ihn automatisch aus:
+
+```python
+"""
+<Einzeiliger Titel des Moduls>
+
+<Optionale längere Beschreibung, was dieses Modul leistet, welche
+Klassen/Funktionen es exportiert und welche Abhängigkeiten es hat.>
+
+:author:  Vorname Nachname <email@beispiel.de>
+:date:    YYYY-MM-DD
+:version: 1.0
+"""
+```
+
+Pflichtfelder: `:author:`, `:date:`  
+Optionale Felder: `:version:`, `:see:`, `:note:`
+
+### Jinja2 / HTML (`.html`)
+
+Jinja2-Kommentare (`{# ... #}`) werden vom Browser nicht gerendert und sind deshalb die richtige Wahl für Template-Header:
+
+```html
+{#
+  Datei:   templates/beispiel.html
+  Autor:   Vorname Nachname <email@beispiel.de>
+  Datum:   YYYY-MM-DD
+  Zweck:   Kurze Beschreibung, welche Seite/Komponente dieses Template rendert
+           und welche Jinja2-Variablen es erwartet.
+#}
+```
+
+Pflichtfelder: `Datei:`, `Autor:`, `Datum:`, `Zweck:`
+
+---
+
+## 2. Dokumentationserzeugung mit Sphinx
+
+Python bietet mit **Sphinx** ein mächtiges Werkzeug analog zu JavaDoc. Es liest Modul-Docstrings (inkl. `:author:`/`:date:`-Felder) und erzeugt daraus eine vollständige HTML-Dokumentation.
+
+### Einrichtung (einmalig)
+
+```bash
+pip install sphinx
+cd docs/
+sphinx-quickstart          # Interaktiver Setup-Assistent
+```
+
+Im Setup-Assistenten:
+- `autodoc` aktivieren (liest Docstrings automatisch)
+- Projektname, Autor und Version eingeben
+
+Anschließend in `docs/conf.py` sicherstellen:
+
+```python
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",   # Links zum Quellcode
+]
+```
+
+### Dokumentation aus dem `app/`-Verzeichnis einlesen
+
+```bash
+sphinx-apidoc -o docs/source/ app/
+```
+
+Dieser Befehl scannt alle `.py`-Dateien unter `app/` und erzeugt `.rst`-Stub-Dateien, die den Modul-Docstring und alle Klassen/Funktionen einbinden.
+
+### Dokumentation bauen
+
+```bash
+cd docs/
+make html
+# Ergebnis liegt unter: docs/_build/html/index.html
+```
+
+### Ablauf
+
+```
+Modul-Docstrings  →  sphinx-apidoc  →  .rst-Dateien  →  make html  →  HTML-Doku
+```
+
+> **Hinweis:** Für HTML-Templates gibt es kein Python-natives Doku-Tool. Die Header-Kommentare dienen dort als Inline-Dokumentation für Entwickler.
+
+---
+
+## 3. Template-Dateien
+
+Im Verzeichnis [`_templates/`](_templates/) liegen Vorlagen, von denen sich der Entwickler **jederzeit eine frische Kopie ziehen** kann:
+
+| Template | Verwendung |
+|---|---|
+| [`_templates/_template.py`](_templates/_template.py) | Neue Python-Quelldatei |
+| [`_templates/_template.html`](_templates/_template.html) | Neues Jinja2/HTML-Template |
+
+### Workflow: neue Datei aus Template erzeugen
+
+```bash
+# Python-Datei
+cp _templates/_template.py app/mein_modul.py
+
+# HTML-Template
+cp _templates/_template.html app/templates/meine_seite.html
+```
+
+Anschließend im kopierten File die Platzhalter (`<...>`) ersetzen.
+
+---
+
+## 4. Kurzreferenz – Pflichtfelder auf einen Blick
+
+| Feldname | Python (Docstring) | HTML (Kommentar) | Pflicht |
+|---|---|---|---|
+| Autor | `:author:` | `Autor:` | Ja |
+| Datum | `:date:` | `Datum:` | Ja |
+| Zweck/Titel | Erste Docstring-Zeile | `Zweck:` | Ja |
+| Version | `:version:` | – | Nein |
+| Dateiname | – | `Datei:` | Ja |