# 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 |