docs: added docs for static site generator

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Documentation Build and Deploy
+
+on:
+  push:
+    branches:
+      - main
+      - '**' # Run on all branches for build/test
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+
+      - uses: reitzig/actions-asciidoctor@v2.0.2
+        with:
+          version: 2.0.26
+
+      - name: run asciidoctor    
+        run:  asciidoctor -R docs -D build/site/html -a docinfo=shared -a toc=left -a toclevels=2 'docs/index.adoc'
+
+      - name: Add CNAME file
+        if: github.ref != 'refs/heads/main'
+        run:  echo 'preview.rfd-fhem.github.io' > "build/site/html/CNAME"
+
+      - name: Add CNAME file
+        if: github.ref == 'refs/heads/main'
+        run:  echo 'pysignalduino.rfd-fhem.github.io' > "build/site/html/CNAME"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: build/site/html
+
+  deploy:
+    permissions:
+      contents: write 
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/01_user_guide/index.adoc

@@ -0,0 +1,7 @@
+= Benutzer-Leitfaden
+:leveloffset: 1
+
+Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino.
+
+include::installation.adoc[]
+include::usage.adoc[]

docs/01_user_guide/installation.adoc

@@ -0,0 +1,25 @@
+= Installation
+
+== Voraussetzungen
+* Python 3.8 oder höher
+* pip (Python Package Installer)
+
+== Installation via pip
+
+Am einfachsten installieren Sie PySignalduino direkt aus dem Repository:
+
+[source,bash]
+----
+git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
+cd PySignalduino
+pip install -r requirements.txt
+----
+
+== Entwicklungsumgebung einrichten
+
+Für Entwickler empfehlen wir die Installation der zusätzlichen Abhängigkeiten (z.B. für Tests):
+
+[source,bash]
+----
+pip install -r requirements-dev.txt
+----

docs/01_user_guide/usage.adoc

@@ -0,0 +1,37 @@
+= Verwendung und Konfiguration
+
+== Grundlegende Nutzung
+
+Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung bereit.
+
+[source,python]
+----
+from sd_protocols import SDProtocols
+
+# Protokolle laden
+sd = SDProtocols()
+
+# Verfügbare Protokolle auflisten
+print(f"Geladene Protokolle: {len(sd.get_protocol_list())}")
+
+# Beispiel: Prüfen ob ein Protokoll existiert
+# ID 10 = Oregon Scientific v2|v3
+if sd.protocol_exists("10"):
+    print("Protokoll 10 (Oregon Scientific v2|v3) ist verfügbar.")
+----
+
+== Integration
+
+PySignalduino ist als Bibliothek konzipiert, die beispielsweise in MQTT-Bridges oder Home-Automation-Skripten verwendet werden kann. Sie übernimmt die Erkennung und Dekodierung der Rohdaten.
+
+=== Logging
+
+Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren:
+
+[source,python]
+----
+def my_logger(message, level):
+    print(f"[LOG LEVEL {level}] {message}")
+
+sd.register_log_callback(my_logger)
+----

docs/02_developer_guide/architecture.adoc

@@ -0,0 +1,31 @@
+= Architektur
+
+== Übersicht
+
+PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).
+
+== Kernkomponenten
+
+=== SDProtocols Klasse
+Die Klasse `SDProtocols` (`sd_protocols/sd_protocols.py`) ist der zentrale Einstiegspunkt. Sie vereint Funktionalitäten durch Mehrfachvererbung von Mixins:
+
+* **ProtocolHelpersMixin:** Grundlegende Bit-Operationen.
+* **ManchesterMixin:** Spezifische Logik für Manchester-kodierte Signale (`mcBit2*` Methoden).
+* **PostdemodulationMixin:** Nachbearbeitung dekodierter Daten (`postDemo_*` Methoden).
+* **RSLMixin:** Handler für das RSL-Protokoll.
+
+=== Protokolldefinition (JSON)
+Die Datei `sd_protocols/protocols.json` enthält die statischen Definitionen. Jedes Protokoll besitzt eine ID und Eigenschaften wie:
+
+* `format`: Kodierung (z.B. `manchester`, `twostate`, `pwm`).
+* `preamble`: Erkennungsmuster.
+* `method`: Mapping auf die Python-Methode zur Dekodierung.
+
+=== Parsing Chain (Manchester)
+
+Der Ablauf bei Manchester-Signalen ist wie folgt:
+1. **Erkennung:** Match anhand der Preamble/Muster.
+2. **Vorvalidierung:** `ManchesterMixin._demodulate_mc_data()` prüft Länge und Taktung.
+3. **Dekodierung:** Aufruf der spezifischen `mcBit2*`-Methode.
+
+*Hinweis:* Einige Protokolle wie TFA (`mcBit2TFA`) oder Grothe (`mcBit2Grothe`) haben spezielle Anforderungen an die Längenprüfung oder Duplikatfilterung.

docs/02_developer_guide/contribution.adoc

@@ -0,0 +1,20 @@
+= Beitrag leisten (Contributing)
+
+Beiträge zum Projekt sind willkommen!
+
+== Workflow
+
+1. **Fork & Clone:** Projekt forken und lokal klonen.
+2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
+3. **Entwicklung:** Änderungen implementieren.
+4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
+5. **Pull Request:** PR auf GitHub öffnen.
+
+== Tests ausführen
+
+Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist.
+
+[source,bash]
+----
+pytest
+----

docs/02_developer_guide/index.adoc

@@ -0,0 +1,6 @@
+= Entwickler-Leitfaden
+
+Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt.
+
+include::architecture.adoc[]
+include::contribution.adoc[]

docs/03_protocol_reference/index.adoc

@@ -0,0 +1,5 @@
+= Protokoll-Referenz
+
+Eine detaillierte Referenz aller unterstützten Protokolle, deren Implementierungsdetails und bekannten Einschränkungen.
+
+include::protocol_details.adoc[]

docs/03_protocol_reference/protocol_details.adoc

@@ -0,0 +1,27 @@
+= Protokolldetails
+
+PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868 MHz Bereich.
+
+== Protokolldefinition
+
+Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Protokollparameter (Timings, Preambles, Methoden).
+
+== Auszug unterstützter Protokolle
+
+* **ID 10:** Oregon Scientific v2/v3 (Manchester, 433 MHz)
+* **ID 13:** Flamingo FA21 Rauchmelder
+* **ID 58:** TFA Wettersensoren
+* **ID 70:** FHT80TF Tür-/Fensterkontakt (868 MHz)
+* **ID 80:** EM1000WZ Energiemonitor
+
+== Protokoll-Typen
+
+* **Manchester:** Selbsttaktend (z.B. Oregon, TFA).
+* **TwoState / PWM:** Kodierung über Pulslängen.
+* **FSK:** Frequenzumtastung (oft bei 868 MHz Geräten wie Lacrosse).
+
+== Neues Protokoll hinzufügen
+
+1. Definition in `protocols.json` ergänzen.
+2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
+3. Tests hinzufügen.

docs/docinfo.html

@@ -0,0 +1,10 @@
+<!-- Fügen Sie alle zusätzlichen <meta>, <link> oder <script> Tags, die in den <head>-Bereich der generierten HTML-Seite eingefügt werden sollen, hier ein. 
+
+    BEISPIEL (für Google Search Console Verifizierung):
+    <meta name="google-site-verification" content="Ihre_Verifizierungs_ID_hier"> 
+
+    BEISPIEL (für benutzerdefinierte Styles):
+    <link rel="stylesheet" href="custom.css">
+-->
+
+<meta name="google-site-verification" content="D0vrv8-mkKHOSvcKXPNS3cVGpYcpEzBL5sFbjfFJ3Rc" />

docs/index.adoc

@@ -0,0 +1,41 @@
+= SIGNALduino - Projektübersicht
+:doctype: book
+:homepage: index.html
+:description: Der SIGNALduino ist ein vielseitiges Funkmodul zum Empfangen und Senden von 433/868MHz Signalen in Smart-Home-Umgebungen wie FHEM. Er dient als Signal-Transceiver und Protokolldekoder.
+:keywords: SIGNALduino, FHEM, 433MHz, 868MHz, Smart Home, Funkprotokolle, DIY, Arduino, ESP32
+:toc: left
+:toclevels: 2
+:experimental:
+
+[[section-uebersicht]]
+== Zweck und Funktion
+
+Der SIGNALduino (bestehend aus Hardware-Stick und Firmware) ist ein leistungsstarkes I/O-Gerät zur Erfassung, zum Empfang und zur Verarbeitung von digitalen Funksignalen (typischerweise 433 MHz und 868 MHz).
+
+Seine Hauptaufgabe ist es, Funksignale anhand von Mustern zu erkennen und sie in maximal detaillierter Form an die übergeordnete Hausautomations-Software (wie FHEM) zur Dekodierung weiterzugeben.
+Dadurch werden verschiedenste proprietäre Funkprotokolle für die Nutzung in Smart-Home-Systemen zugänglich.
+
+Die verfügbare Hardware-Basis reicht von einfachen Arduino/nanoCUL-Lösungen bis hin zu erweiterten Varianten wie dem Maple-SignalDuino und dem ESP32-SignalDuino, die erweiterte Funktionen (z.B. WLAN) bieten.
+
+image::images/signalduino_uebersicht.png[SIGNALduino Übersicht - Hardware und Funktion]
+
+[[section-protokolle]]
+== Unterstützte Protokolle
+
+Eine breite Palette von Funkprotokollen wird unterstützt und ständig erweitert.
+Detaillierte Informationen zu den unterstützten Geräten und Protokollen finden Sie im Benutzerhandbuch.
+
+[[section-firmware]]
+== Firmware
+
+Die Firmware wird kontinuierlich weiterentwickelt und ist nicht auf jedem prinzipiell geeigneten Gerät lauffähig, da spezifische Anpassungen an die Hardware erforderlich sind.
+
+include::01_user_guide/installation.adoc[]
+
+include::01_user_guide/usage.adoc[]
+
+include::02_developer_guide/architecture.adoc[]
+
+include::02_developer_guide/contribution.adoc[]
+
+include::03_protocol_reference/protocol_details.adoc[]