Skip to content

Commit 56ca564

Browse files
sidey79sidey79
authored
Merge pull request #9 from RFD-FHEM/fix/docs
fix(docs): improve documentation clarity and formatting across multip…
2 parents 0572d15 + b63dfb4 commit 56ca564

19 files changed

Lines changed: 150 additions & 109 deletions

‎.devcontainer/.devcontainer.env.sample‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,11 @@ MQTT_USERNAME=
1313
# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
1414
MQTT_PASSWORD=
1515

16-
# Das Basis-Topic für Signalduino Nachrichten.
17-
# Nachrichten werden unter $MQTT_TOPIC/<protokoll_id> veröffentlicht.
18-
# Befehle werden unter $MQTT_TOPIC/commands/# erwartet.
19-
MQTT_TOPIC=signalduino/messages
16+
# Das Basis-Topic (Root-Präfix) für MQTT-Kommunikation.
17+
# Der Code hängt automatisch '/v1' an, um das Basis-Topic zu versionieren (z.B. 'signalduino/v1').
18+
# Nachrichten werden unter $MQTT_TOPIC/v1/state/messages veröffentlicht.
19+
# Befehle werden unter $MQTT_TOPIC/v1/commands/# erwartet.
20+
MQTT_TOPIC=signalduino
2021

2122
# Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py)
2223
# Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung.

‎.github/workflows/docs.yml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,18 @@ jobs:
2020
with:
2121
ruby-version: 3.4
2222

23+
# INSTALLATION: Installiere asciidoctor-kroki Gem für Mermaid-Unterstützung
24+
- name: Install Asciidoctor Kroki Gem
25+
run: gem install asciidoctor-kroki
26+
2327
- uses: reitzig/actions-asciidoctor@v2.0.2
2428
with:
2529
version: 2.0.26
2630

27-
- name: run asciidoctor
28-
run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc'
31+
- name: run asciidoctor with Kroki extension
32+
# Registriere die Kroki-Extension (-r asciidoctor-kroki) und aktiviere sie (-a kroki=).
33+
# Mermaid-Diagramme werden mit dem Kroki-Server gerendert.
34+
run: asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= 'docs/index.adoc'
2935

3036
- name: Setup Python for Sitemap Generation
3137
uses: actions/setup-python@v5

‎docs/01_user_guide/index.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,10 +71,10 @@ Die Hauptkomponenten sind:
7171

7272
Für einen schnellen Einstieg folgen Sie diesen Schritten:
7373

74-
1. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
75-
2. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
76-
3. **Programm starten**: Führen Sie `python3 main.py` aus.
77-
4. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
74+
. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
75+
. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
76+
. **Programm starten**: Führen Sie `python3 main.py` aus.
77+
. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
7878

7979
Ausführliche Anleitungen finden Sie in den folgenden Kapiteln.
8080

‎docs/01_user_guide/installation.adoc‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
= Installation
1+
== Installation
22

33
[NOTE]
44
====
5-
PySignalduino ist noch in Entwicklung. Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
5+
PySignalduino ist noch in Entwicklung.
6+
Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
67
====
78

89
== Voraussetzungen
@@ -30,7 +31,9 @@ Die einfachste Methode ist die Installation aus dem geklonten Repository im Entw
3031

3132
[source,bash]
3233
----
33-
include::../examples/bash/install_via_pip.sh[]
34+
git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
35+
cd PySignalduino
36+
pip install -e .
3437
----
3538

3639
Dadurch wird das Paket `signalduino-mqtt` in Ihrer Python-Umgebung installiert und alle Runtime-Abhängigkeiten werden erfüllt.
@@ -41,7 +44,7 @@ Falls Sie das Paket nicht installieren, sondern nur die Abhängigkeiten nutzen m
4144

4245
[source,bash]
4346
----
44-
include::../examples/bash/install_requirements.sh[]
47+
pip install -r requirements.txt
4548
----
4649

4750
Die Datei `requirements.txt` enthält die gleichen Pakete wie oben aufgelistet.
@@ -52,7 +55,7 @@ Für Beiträge zum Projekt oder zum Ausführen der Tests installieren Sie zusät
5255

5356
[source,bash]
5457
----
55-
include::../examples/bash/install_dev_requirements.sh[]
58+
pip install -r requirements-dev.txt
5659
----
5760

5861
Dies installiert:
@@ -68,7 +71,7 @@ Dies installiert:
6871

6972
[source,bash]
7073
----
71-
include::../examples/bash/verify_installation.sh[]
74+
python3 main.py --help
7275
----
7376

7477
Sie sollten eine Ausgabe mit allen verfügbaren Kommandozeilenoptionen sehen.

‎docs/01_user_guide/mqtt_api.adoc‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
= MQTT API Reference
2-
:doctype: book
3-
:icons: font
4-
:toc: left
5-
:toclevels: 2
2+
:doctype: book :icons: font :toc: left :toclevels: 2
63
:sectnums:
74

85
[[_mqtt_introduction]]
@@ -12,7 +9,9 @@ Die MQTT-Schnittstelle ermöglicht die Steuerung des PySignalduino-Gateways und
129

1310
=== Topics und Struktur
1411

15-
Die Basis aller Topics ist `<base_topic>/v1`, wobei `<base_topic>` standardmäßig `signalduino` ist. Alle Beispiele verwenden `signalduino/v1` als Basis.
12+
Der **Standard-Topic** für alle MQTT-Operationen ist `signalduino/v1`.
13+
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`.
14+
Alle nachfolgenden Beispiele verwenden `signalduino/v1` als Basis.
1615

1716
|===
1817
| Zweck | Topic-Format | Anmerkungen

‎docs/01_user_guide/usage.adoc‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ include::../../main.py[lines=55..84]
5454

5555
==== Heartbeat-Funktionalität
5656

57-
Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht. Bei Verbindungsabbruch wird „offline“ gepublished.
57+
Der Publisher sendet regelmäßig einen Heartbeat („online“) unter `{topic}/status`, solange die Verbindung besteht.
58+
Bei Verbindungsabbruch wird „offline“ gepublished.
5859

5960
==== Beispiel: Manuelle Nutzung des MqttPublisher
6061

@@ -106,7 +107,9 @@ Die folgenden Befehle werden unterstützt (Auswahl):
106107

107108
==== Persistenz-Funktionalität
108109

109-
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.
110+
Befehle, die die Hardware-Konfiguration ändern (z.
111+
B. `write_register`, `set_patable`), werden in der Regel im EEPROM des SIGNALDuino persistent gespeichert.
112+
Die Persistenz wird durch die Firmware gewährleistet; PySignalduino sendet lediglich die entsprechenden Kommandos.
110113

111114
==== Nutzung über MQTT
112115

‎docs/02_developer_guide/architecture.adoc‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
== Übersicht
44

5-
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.
5+
PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).
6+
Seit der Migration zu asyncio (Version 0.9.0) folgt das System einer ereignisgesteuerten, asynchronen Architektur, die auf asyncio-Tasks und -Queues basiert.
7+
Dies ermöglicht eine effiziente Verarbeitung von Sensordaten, Kommandos und MQTT-Nachrichten ohne Blockierung.
68

79
== Kernkomponenten
810

@@ -154,9 +156,10 @@ Die Sitemap wird durch das Python-Skript `tools/generate_sitemap.py` generiert,
154156

155157
Das Skript kann manuell ausgeführt werden:
156158

157-
```bash
159+
[source,bash]
160+
----
158161
python tools/generate_sitemap.py --build-dir build/site/html --output sitemap.xml --branch main
159-
```
162+
----
160163

161164
=== robots.txt-Konfiguration
162165

‎docs/02_developer_guide/contribution.adoc‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,19 @@
22

33
[NOTE]
44
====
5-
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.
5+
Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern.
6+
Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.
67
====
78

89
Beiträge zum Projekt sind willkommen!
910

1011
== Workflow
1112

12-
1. **Fork & Clone:** Projekt forken und lokal klonen.
13-
2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
14-
3. **Entwicklung:** Änderungen implementieren.
15-
4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
16-
5. **Pull Request:** PR auf GitHub öffnen.
13+
. **Fork & Clone:** Projekt forken und lokal klonen.
14+
. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
15+
. **Entwicklung:** Änderungen implementieren.
16+
. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
17+
. **Pull Request:** PR auf GitHub öffnen.
1718

1819
== Entwicklungsumgebung
1920

@@ -23,7 +24,7 @@ Das Projekt verwendet `poetry` für die Abhängigkeitsverwaltung. Installieren S
2324

2425
[source,bash]
2526
----
26-
include::../../examples/bash/install_dev_deps.sh[]
27+
include::../examples/bash/install_dev_deps.sh[]
2728
----
2829

2930
Oder verwenden Sie `poetry install` (falls Poetry konfiguriert ist).
@@ -42,25 +43,37 @@ Das Projekt folgt PEP 8. Verwenden Sie `black` für automatische Formatierung un
4243

4344
[source,bash]
4445
----
45-
include::../../examples/bash/format_code.sh[]
46+
include::../examples/bash/format_code.sh[]
4647
----
4748

4849
Es gibt keine strikte CI-Prüfung, aber konsistenter Stil wird erwartet.
4950

51+
=== Dokumentationsstil
52+
53+
Für alle AsciiDoc-Dateien im `docs/` Verzeichnis ist die Regel "Ein Satz pro Zeile" verpflichtend.
54+
Dies erleichtert die Überprüfung von Änderungen mittels `git diff`.
55+
56+
[IMPORTANT]
57+
====
58+
Jeder Satz muss auf einer neuen Zeile beginnen.
59+
Ein Satz endet typischerweise mit einem Punkt (`.`), Ausrufezeichen (`!`) oder Fragezeichen (`?`).
60+
Achten Sie darauf, dass Codeblöcke und Tabellen nicht betroffen sind.
61+
====
62+
5063
== Tests ausführen
5164

5265
Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist.
5366

5467
[source,bash]
5568
----
56-
include::../../examples/bash/run_pytest.sh[]
69+
include::../examples/bash/run_pytest.sh[]
5770
----
5871

5972
Für spezifische Testmodule:
6073

6174
[source,bash]
6275
----
63-
include::../../examples/bash/run_specific_tests.sh[]
76+
include::../examples/bash/run_specific_tests.sh[]
6477
----
6578

6679
=== Asyncio-Tests
@@ -91,7 +104,7 @@ Coverage-Bericht generieren:
91104

92105
[source,bash]
93106
----
94-
include::../../examples/bash/coverage_report.sh[]
107+
include::../examples/bash/coverage_report.sh[]
95108
----
96109

97110
Der Bericht wird im Verzeichnis `htmlcov/` erstellt.

‎docs/02_developer_guide/index.adoc‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@
22

33
Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt.
44

5-
include::architecture.adoc[]
6-
include::contribution.adoc[]
5+
include::architecture.adoc[] include::contribution.adoc[]
76

87
== Weitere Ressourcen
98

‎docs/03_protocol_reference/protocol_details.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,6 @@ Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Prot
2222

2323
== Neues Protokoll hinzufügen
2424

25-
1. Definition in `protocols.json` ergänzen.
26-
2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
27-
3. Tests hinzufügen.
25+
. Definition in `protocols.json` ergänzen.
26+
. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
27+
. Tests hinzufügen.

0 commit comments

Comments
 (0)