132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# 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 |
|