fix(docs): improve documentation clarity and formatting across multiple files

Author: sidey79

.devcontainer/.devcontainer.env.sample

@@ -13,10 +13,11 @@ MQTT_USERNAME=
 # Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
 MQTT_PASSWORD=
 
-# Das Basis-Topic für Signalduino Nachrichten.
-# Nachrichten werden unter $MQTT_TOPIC/<protokoll_id> veröffentlicht.
-# Befehle werden unter $MQTT_TOPIC/commands/# erwartet.
-MQTT_TOPIC=signalduino/messages
+# Das Basis-Topic (Root-Präfix) für MQTT-Kommunikation.
+# Der Code hängt automatisch '/v1' an, um das Basis-Topic zu versionieren (z.B. 'signalduino/v1').
+# Nachrichten werden unter $MQTT_TOPIC/v1/state/messages veröffentlicht.
+# Befehle werden unter $MQTT_TOPIC/v1/commands/# erwartet.
+MQTT_TOPIC=signalduino
 
 # Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py)
 # Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung.

docs/01_user_guide/installation.adoc

@@ -2,8 +2,8 @@
 
 [NOTE]
 ====
-PySignalduino ist noch in Entwicklung. Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
-====
+PySignalduino ist noch in Entwicklung.
+Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
 
 == Voraussetzungen
 

docs/01_user_guide/mqtt_api.adoc

@@ -1,8 +1,5 @@
 = MQTT API Reference
-:doctype: book
-:icons: font
-:toc: left
-:toclevels: 2
+:doctype: book :icons: font :toc: left :toclevels: 2
 :sectnums:
 
 [[_mqtt_introduction]]
@@ -12,7 +9,9 @@ Die MQTT-Schnittstelle ermöglicht die Steuerung des PySignalduino-Gateways und
 
 === Topics und Struktur
 
-Die Basis aller Topics ist `<base_topic>/v1`, wobei `<base_topic>` standardmäßig `signalduino` ist. Alle Beispiele verwenden `signalduino/v1` als Basis.
+Der **Standard-Topic** für alle MQTT-Operationen ist `signalduino/v1`. 
+Dieser Wert kann über die Umgebungsvariable `MQTT_TOPIC` oder den CLI-Parameter `--mqtt-topic` angepasst werden. Wenn nur der Basis-Topic (z.B. `foo`) gesetzt wird, ist der finale Topic immer versionsspezifisch: `foo/v1`.
+Alle nachfolgenden Beispiele verwenden `signalduino/v1` als Basis.
 
 |===
 | Zweck | Topic-Format | Anmerkungen

docs/01_user_guide/usage.adoc

@@ -54,7 +54,8 @@ include::../../main.py[lines=55..84]
 
 ==== Heartbeat-Funktionalität
 
-Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht. Bei Verbindungsabbruch wird „offline“ gepublished.
+Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht.
+Bei Verbindungsabbruch wird „offline“ gepublished.
 
 ==== Beispiel: Manuelle Nutzung des MqttPublisher
 
@@ -106,7 +107,9 @@ Die folgenden Befehle werden unterstützt (Auswahl):
 
 ==== Persistenz-Funktionalität
 
-Befehle, die die Hardware-Konfiguration ändern (z. B. `write_register`, `set_patable`), werden in der Regel im EEPROM des SIGNALDuino persistent gespeichert. Die Persistenz wird durch die Firmware gewährleistet; PySignalduino sendet lediglich die entsprechenden Kommandos.
+Befehle, die die Hardware-Konfiguration ändern (z.
+B. `write_register`, `set_patable`), werden in der Regel im EEPROM des SIGNALDuino persistent gespeichert.
+Die Persistenz wird durch die Firmware gewährleistet; PySignalduino sendet lediglich die entsprechenden Kommandos.
 
 ==== Nutzung über MQTT
 

docs/02_developer_guide/architecture.adoc

@@ -2,7 +2,9 @@
 
 == Übersicht
 
-PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python). Seit der Migration zu asyncio (Version 0.9.0) folgt das System einer ereignisgesteuerten, asynchronen Architektur, die auf asyncio-Tasks und -Queues basiert. Dies ermöglicht eine effiziente Verarbeitung von Sensordaten, Kommandos und MQTT-Nachrichten ohne Blockierung.
+PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).
+Seit der Migration zu asyncio (Version 0.9.0) folgt das System einer ereignisgesteuerten, asynchronen Architektur, die auf asyncio-Tasks und -Queues basiert.
+Dies ermöglicht eine effiziente Verarbeitung von Sensordaten, Kommandos und MQTT-Nachrichten ohne Blockierung.
 
 == Kernkomponenten
 
@@ -154,9 +156,10 @@ Die Sitemap wird durch das Python-Skript `tools/generate_sitemap.py` generiert,
 
 Das Skript kann manuell ausgeführt werden:
 
-```bash
+[source,bash]
+----
 python tools/generate_sitemap.py --build-dir build/site/html --output sitemap.xml --branch main
-```
+----
 
 === robots.txt-Konfiguration
 

docs/02_developer_guide/contribution.adoc

@@ -2,8 +2,8 @@
 
 [NOTE]
 ====
-Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern. Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.
-====
+Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern.
+Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.
 
 Beiträge zum Projekt sind willkommen!
 
@@ -23,7 +23,7 @@ Das Projekt verwendet `poetry` für die Abhängigkeitsverwaltung. Installieren S
 
 [source,bash]
 ----
-include::../../examples/bash/install_dev_deps.sh[]
+include::../examples/bash/install_dev_deps.sh[]
 ----
 
 Oder verwenden Sie `poetry install` (falls Poetry konfiguriert ist).
@@ -42,25 +42,36 @@ Das Projekt folgt PEP 8. Verwenden Sie `black` für automatische Formatierung un
 
 [source,bash]
 ----
-include::../../examples/bash/format_code.sh[]
+include::../examples/bash/format_code.sh[]
 ----
 
 Es gibt keine strikte CI-Prüfung, aber konsistenter Stil wird erwartet.
 
+=== Dokumentationsstil
+
+Für alle AsciiDoc-Dateien im `docs/` Verzeichnis ist die Regel "Ein Satz pro Zeile" verpflichtend.
+Dies erleichtert die Überprüfung von Änderungen mittels `git diff`.
+
+[NOTE]
+====
+Jeder Satz muss auf einer neuen Zeile beginnen.
+Ein Satz endet typischerweise mit einem Punkt (`.`), Ausrufezeichen (`!`) oder Fragezeichen (`?`).
+Achten Sie darauf, dass Codeblöcke und Tabellen nicht betroffen sind.
+
 == Tests ausführen
 
 Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist.
 
 [source,bash]
 ----
-include::../../examples/bash/run_pytest.sh[]
+include::../examples/bash/run_pytest.sh[]
 ----
 
 Für spezifische Testmodule:
 
 [source,bash]
 ----
-include::../../examples/bash/run_specific_tests.sh[]
+include::../examples/bash/run_specific_tests.sh[]
 ----
 
 === Asyncio-Tests
@@ -91,7 +102,7 @@ Coverage-Bericht generieren:
 
 [source,bash]
 ----
-include::../../examples/bash/coverage_report.sh[]
+include::../examples/bash/coverage_report.sh[]
 ----
 
 Der Bericht wird im Verzeichnis `htmlcov/` erstellt.

docs/02_developer_guide/index.adoc

@@ -2,8 +2,7 @@
 
 Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt.
 
-include::architecture.adoc[]
-include::contribution.adoc[]
+include::architecture.adoc[] include::contribution.adoc[]
 
 == Weitere Ressourcen
 

docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc

@@ -1,7 +1,5 @@
 = 001. Implementierung des MQTT-Befehls get/frequency
-:author: Roo
-:revdate: 2026-01-03
-:status: Accepted
+:author: Roo :revdate: 2026-01-03 :status: Accepted
 
 [[status]]
 == Status

docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc

@@ -1,10 +1,5 @@
 = ADR 002: Verwendung des MqttCommandDispatcher für die MQTT-Befehlsbehandlung
-:doctype: article
-:encoding: utf-8
-:lang: de
-:status: Accepted
-:decided-at: 2026-01-04
-:decided-by: Roo (Architekt)
+:doctype: article :encoding: utf-8 :lang: de :status: Accepted :decided-at: 2026-01-04 :decided-by: Roo (Architekt)
 
 [[kontext]]
 == Kontext
@@ -40,4 +35,4 @@ Die hartcodierte `if/elif`-Logik in `signalduino/mqtt.py` wird durch die Verwend
 [[alternativen]]
 == Alternativen
 * **Beibehaltung der if/elif-Kette:** Dies wurde abgelehnt, da es gegen die Prinzipien der Wartbarkeit und der Single Responsibility Principle (SRP) verstößt.
-* **Anderer Dispatch-Mechanismus:** Die Verwendung des vorhandenen `MqttCommandDispatcher` ist die pragmatischste Lösung, da die Klasse bereits existiert und die Validierungsinfrastruktur bietet.
+* **Anderer Dispatch-Mechanismus:** Die Verwendung des vorhandenen `MqttCommandDispatcher` ist die pragmatischste Lösung, da die Klasse bereits existiert und die Validierungsinfrastruktur bietet.

docs/architecture/decisions/ADR-003-cc1101-parameter-set-logic.adoc

@@ -1,19 +1,20 @@
 = 003. Verwendung von CC1101-Standardformeln für Frequenz und Datenrate
-:revdate: 2026-01-04
-:status: Accepted
+:revdate: 2026-01-04 :status: Accepted
 
 == Context
 Die Implementierung der MQTT SET-Befehle für CC1101-Parameter (Frequenz, Datenrate) erfordert die Umrechnung von physikalischen Werten (MHz, kBaud) in die spezifischen Registerwerte des CC1101-Chips.
 
 Andere Parameter wie Bandbreite, Sensitivity und Rampl verwendeten früher spezielle, abstraktere Kommandos des Signalduino-Firmware-Protokolls (`C101`, `X4C`, `X5C`).
 
-Um die Steuerung der CC1101-Parameter zu konsolidieren, wurden die Spezialbefehle (`X4C`, `X5C`) in der Python-Implementierung durch generische Register-Writes (`W`) ersetzt, wobei die Umrechnungslogik (z.B. Index in Registerwert) in Python implementiert wurde.
+Um die Steuerung der CC1101-Parameter zu konsolidieren, wurden die Spezialbefehle (`X4C`, `X5C`) in der Python-Implementierung durch generische Register-Writes (`W`) ersetzt, wobei die Umrechnungslogik (z.B.
+Index in Registerwert) in Python implementiert wurde.
 
 Für Frequenz und Datenrate existiert keine solche Abstraktion im Signalduino-Protokoll, oder die vorhandene Logik ist unvollständig/unzureichend für eine präzise Steuerung.
 
 
 == Decision
-Die Umrechnung von Frequenz (MHz) in die drei Registerwerte (FREQ2, FREQ1, FREQ0) und die Umrechnung der Datenrate (kBaud) in MDMCFG4/MDMCFG3-Registerwerte erfolgt *direkt* in der Python-Implementierung von `SignalduinoCommands` unter Verwendung der im CC1101-Datenblatt definierten Standardformeln (z.B. Freq = f_xosc * FREQ / 2^16).
+Die Umrechnung von Frequenz (MHz) in die drei Registerwerte (FREQ2, FREQ1, FREQ0) und die Umrechnung der Datenrate (kBaud) in MDMCFG4/MDMCFG3-Registerwerte erfolgt *direkt* in der Python-Implementierung von `SignalduinoCommands` unter Verwendung der im CC1101-Datenblatt definierten Standardformeln (z.B.
+Freq = f_xosc * FREQ / 2^16).
 
 Diese Registerwerte werden dann über generische CC1101-Schreibbefehle des Signalduino-Protokolls (`W<RegisterAddress><Value>`) übertragen.
 
@@ -28,4 +29,4 @@ Nach dem Senden aller Register-SET-Befehle muss die Methode `SignalduinoCommands
 * **Alternative 1: Nur Signalduino-Spezialbefehle verwenden:**
   * _Ablehnungsgrund:_ Für Frequenz und Datenrate gibt es keine oder keine ausreichend präzisen/dokumentierten Signalduino-Spezialbefehle, die eine Einstellung über MQTT in physikalischen Einheiten (MHz, kBaud) ermöglichen.
 * **Alternative 2: Berechnung in die Controller-Klasse verschieben:**
-  * _Ablehnungsgrund:_ Die `SignalduinoCommands`-Klasse ist der logische Ort für die Umrechnung von physikalischen Einheiten in serielle Protokolle, da sie die Schnittstelle zum physischen Gerät darstellt. Die `SignalduinoController`-Klasse soll nur die MQTT-Payload entpacken.
+  * _Ablehnungsgrund:_ Die `SignalduinoCommands`-Klasse ist der logische Ort für die Umrechnung von physikalischen Einheiten in serielle Protokolle, da sie die Schnittstelle zum physischen Gerät darstellt. Die `SignalduinoController`-Klasse soll nur die MQTT-Payload entpacken.