chmln-app-dev/kbcrm

0 Fork 0

Files

T

br 5126decf36 init

2026-06-18 08:38:37 +02:00

3.5 KiB

Raw Permalink Blame History

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:

"""
<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:

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

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:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",   # Links zum Quellcode
]

Dokumentation aus dem `app/`-Verzeichnis einlesen

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

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/ liegen Vorlagen, von denen sich der Entwickler jederzeit eine frische Kopie ziehen kann:

Template	Verwendung
`_templates/_template.py`	Neue Python-Quelldatei
`_templates/_template.html`	Neues Jinja2/HTML-Template

Workflow: neue Datei aus Template erzeugen

# 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

3.5 KiB Raw Permalink Blame History Unescape Escape