Merge pull request #13 from RFD-FHEM/feat/demoDocs

Add some demo to the docs

Author: sidey79

.devcontainer/fhem-data/fhem_signalduino_example.cfg

@@ -25,12 +25,16 @@ attr WEB stylesheetPrefix dark
 define eventTypes eventTypes ./log/eventTypes.txt
 setuuid eventTypes 695e9c21-f33f-c986-9ac3-190c47641a98acb9
 
+
+# tag::broker_config[]
 # 4. Define the MQTT Client (Broker Connection)
 # 'mqtt' is the hostname of the broker service in docker-compose.yml
 define mqtt_broker MQTT2_CLIENT mqtt:1883
 setuuid mqtt_broker 695e9c21-f33f-c986-e617-d7301881c4685bc6
 attr mqtt_broker autocreate simple
+# end::broker_config[]
 
+# tag::device_config[]
 # 5. Define the SignalDuino MQTT Device
 define PySignalDuino MQTT2_DEVICE
 setuuid PySignalDuino 695e9c21-f33f-c986-4f81-a9f0ab37b6bcedf8
@@ -75,6 +79,7 @@ attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPAR
   # Maintenance commands \
   factory_reset:noArg signalduino/v1/commands/set/factory_reset
 attr PySignalDuino stateFormat state
+# end::device_config[]
 # Map JSON payload to readings
 # Define setter commands
 

.github/workflows/docs.yml

@@ -31,7 +31,10 @@ jobs:
       - name: run asciidoctor with Kroki extension
         # Registriere die Kroki-Extension (-r asciidoctor-kroki) und aktiviere sie (-a kroki=). 
         # Mermaid-Diagramme werden mit dem Kroki-Server gerendert.
-        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'
+        # Verwendung von -R docs, um die Verzeichnisstruktur unter build/site/html beizubehalten
+        run: |
+          shopt -s globstar
+          asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 -r asciidoctor-kroki -a kroki= docs/**/*.adoc
       
       - name: Setup Python for Sitemap Generation
         uses: actions/setup-python@v5

README.adoc

@@ -0,0 +1,93 @@
+= PySignalduino – Asynchrone MQTT-Bridge für SIGNALDuino
+:sectlinks:
+
+Dieses Projekt ist eine moderne Python-Implementierung der SIGNALDuino-Protokolle mit vollständiger *asyncio*-Unterstützung und integrierter *MQTT-Bridge*. Es ermöglicht die Kommunikation mit SIGNALDuino-Hardware (über serielle Schnittstelle oder TCP) und veröffentlicht empfangene Signale sowie empfängt Steuerbefehle über MQTT.
+
+=== Entwicklungsstatus
+
+[NOTE]
+.Entwicklungsstatus
+====
+PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
+====
+
+=== PySignalduino vs. Original
+PySignalduino ist keine direkte Portierung, sondern eine Neuimplementierung mit folgenden Unterschieden:
+* *Asynchrone Verarbeitung*:: Statt Threads wird `asyncio` verwendet.
+* *MQTT-Integration*:: Eingebaute MQTT-Bridge für nahtlose Integration in IoT-Ökosysteme.
+* *Moderne Python-Praktiken*:: Typisierung, strukturierte Logging, Konfiguration über Umgebungsvariablen.
+
+== Controller-Code und Firmware
+
+Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Repository entwickelt:
+
+* *GitHub Repository*:: https://github.com/RFD-FHEM/SIGNALDuino
+* *Aktuelle Version*:: v4.0.0
+* *Unterstützte Hardware*::
+** Arduino Nano mit CC1101
+** ESP32-basierte Boards (z.B. ESP32-DevKitC)
+** Maple Mini (STM32)
+* *Build-Anleitungen*:: Das Repository enthält PlatformIO-Konfigurationen und Arduino-IDE-Projektdateien für einfache Kompilierung.
+
+== Hauptmerkmale
+
+* **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.
+* **MQTT-Integration** – Automatisches Publizieren dekodierter Nachrichten in konfigurierbare Topics und Empfang von Steuerbefehlen (z.B. `version`, `set`, `mqtt`).
+* **Unterstützte Transporte** – Serielle Verbindung (über `pyserial-asyncio`) und TCP-Verbindung.
+* **Umfangreiche Protokollbibliothek** – Portierung der originalen FHEM‑SIGNALDuino‑Protokolle mit `SDProtocols` und `SDProtocolData`.
+* **Konfiguration über Umgebungsvariablen** – Einfache Einrichtung ohne Codeänderungen.
+* **Ausführbares Hauptprogramm** – `main.py` bietet eine sofort einsatzbereite Lösung mit Logging, Signalbehandlung und Timeout‑Steuerung.
+* **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten.
+
+== Demo
+
+=== MQTT-CLI-Integration
+
+image::docs/pysignalduino_cli.apng[PySignalduino CLI Demo]
+
+=== FHEMweb-Integration
+
+image::docs/pysignalduino_fhemweb.apng[PySignalduino FHEMweb Demo]
+
+== Projektstruktur
+
+[source,text]
+----
+PySignalduino/
+├── signalduino/              # Hauptpaket
+│   ├── controller.py         # Asynchroner Controller
+│   ├── mqtt.py               # MQTT‑Publisher/Subscriber
+│   ├── transport.py          # Serielle/TCP‑Transporte (asyncio)
+│   ├── commands.py           # Befehlsimplementierung
+│   └── ...
+├── sd_protocols/             # Protokollbibliothek (SDProtocols)
+├── tests/                    # Umfangreiche Testsuite
+├── docs/                     # Dokumentation (AsciiDoc)
+├── main.py                   # Ausführbares Hauptprogramm
+├── pyproject.toml            # Paketkonfiguration
+└── requirements*.txt         # Abhängigkeiten
+----
+
+== Dokumentation
+
+Die vollständige Dokumentation und alle Anleitungen finden Sie auf der Hauptseite:
+
+* xref:docs/index.adoc[Zur vollständigen PySignalduino Dokumentation]
+
+== SEO & Sitemap
+
+Die Dokumentation wird automatisch mit einer dynamischen Sitemap (`sitemap.xml`) und branch‑spezifischen `robots.txt`‑Dateien versehen, um die Auffindbarkeit in Suchmaschinen zu verbessern.
+
+* *Sitemap‑Generierung*:: Das Skript xref:tools/generate_sitemap.py[tools/generate_sitemap.py] scannt den Build‑Output, weist Prioritäten und Update‑Frequenzen zu und generiert eine valide XML‑Sitemap gemäß sitemaps.org.
+* *Branch‑spezifische URLs*:: Für die Branches `main`, `preview` und `develop` werden unterschiedliche Base‑URLs verwendet.
+* *Integration in CI/CD*:: Der GitHub Actions Workflow link:.github/workflows/docs.yml[.github/workflows/docs.yml] generiert die Sitemap automatisch nach jedem Build und passt die `robots.txt` entsprechend an.
+
+Weitere Details zur Architektur finden Sie im xref:docs/02_developer_guide/architecture.adoc#dokumentations-infrastruktur-sitemap--seo[Architektur‑Dokument].
+
+== Lizenz
+
+Dieses Projekt steht unter der MIT‑Lizenz – siehe xref:LICENSE[LICENSE] für Details.
+
+== Danksagung
+
+Basierend auf der originalen FHEM‑SIGNALDuino‑Implementierung von [@Sidey79](https://github.com/Sidey79) und der Community.