Skip to content

Commit c912ad0

Browse files
sidey79sidey79
authored
Merge pull request #4 from RFD-FHEM/feat/docs
docs: added docs for static site generator
2 parents 873e8a7 + 423e8b9 commit c912ad0

File tree

11 files changed

+265
-0
lines changed

11 files changed

+265
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Documentation Build and Deploy
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- '**' # Run on all branches for build/test
8+
workflow_dispatch:
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
concurrency:
14+
group: ${{ github.workflow }}-${{ github.ref }}
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
19+
- uses: ruby/setup-ruby@v1
20+
with:
21+
ruby-version: 3.4
22+
23+
- uses: reitzig/actions-asciidoctor@v2.0.2
24+
with:
25+
version: 2.0.26
26+
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'
29+
30+
- name: Add CNAME file
31+
if: github.ref != 'refs/heads/main'
32+
run: echo 'preview.rfd-fhem.github.io' > "build/site/html/CNAME"
33+
34+
- name: Add CNAME file
35+
if: github.ref == 'refs/heads/main'
36+
run: echo 'pysignalduino.rfd-fhem.github.io' > "build/site/html/CNAME"
37+
38+
- name: Upload artifact
39+
uses: actions/upload-pages-artifact@v4
40+
with:
41+
path: build/site/html
42+
43+
deploy:
44+
permissions:
45+
contents: write
46+
pages: write
47+
id-token: write
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
runs-on: ubuntu-latest
52+
needs: build
53+
steps:
54+
- name: Deploy to GitHub Pages
55+
id: deployment
56+
uses: actions/deploy-pages@v4

‎docs/01_user_guide/index.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
= Benutzer-Leitfaden
2+
:leveloffset: 1
3+
4+
Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino.
5+
6+
include::installation.adoc[]
7+
include::usage.adoc[]

‎docs/01_user_guide/installation.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
= Installation
2+
3+
== Voraussetzungen
4+
* Python 3.8 oder höher
5+
* pip (Python Package Installer)
6+
7+
== Installation via pip
8+
9+
Am einfachsten installieren Sie PySignalduino direkt aus dem Repository:
10+
11+
[source,bash]
12+
----
13+
git clone https://github.com/Ein-Einfaches-Beispiel/PySignalduino.git
14+
cd PySignalduino
15+
pip install -r requirements.txt
16+
----
17+
18+
== Entwicklungsumgebung einrichten
19+
20+
Für Entwickler empfehlen wir die Installation der zusätzlichen Abhängigkeiten (z.B. für Tests):
21+
22+
[source,bash]
23+
----
24+
pip install -r requirements-dev.txt
25+
----

‎docs/01_user_guide/usage.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
= Verwendung und Konfiguration
2+
3+
== Grundlegende Nutzung
4+
5+
Die Hauptklasse `SDProtocols` stellt die Schnittstelle zur Protokollverarbeitung bereit.
6+
7+
[source,python]
8+
----
9+
from sd_protocols import SDProtocols
10+
11+
# Protokolle laden
12+
sd = SDProtocols()
13+
14+
# Verfügbare Protokolle auflisten
15+
print(f"Geladene Protokolle: {len(sd.get_protocol_list())}")
16+
17+
# Beispiel: Prüfen ob ein Protokoll existiert
18+
# ID 10 = Oregon Scientific v2|v3
19+
if sd.protocol_exists("10"):
20+
print("Protokoll 10 (Oregon Scientific v2|v3) ist verfügbar.")
21+
----
22+
23+
== Integration
24+
25+
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.
26+
27+
=== Logging
28+
29+
Für Debugging-Zwecke können Sie eine eigene Callback-Funktion registrieren:
30+
31+
[source,python]
32+
----
33+
def my_logger(message, level):
34+
print(f"[LOG LEVEL {level}] {message}")
35+
36+
sd.register_log_callback(my_logger)
37+
----

‎docs/02_developer_guide/architecture.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
= Architektur
2+
3+
== Übersicht
4+
5+
PySignalduino ist modular aufgebaut und trennt die Protokolldefinitionen (JSON) strikt von der Verarbeitungslogik (Python).
6+
7+
== Kernkomponenten
8+
9+
=== SDProtocols Klasse
10+
Die Klasse `SDProtocols` (`sd_protocols/sd_protocols.py`) ist der zentrale Einstiegspunkt. Sie vereint Funktionalitäten durch Mehrfachvererbung von Mixins:
11+
12+
* **ProtocolHelpersMixin:** Grundlegende Bit-Operationen.
13+
* **ManchesterMixin:** Spezifische Logik für Manchester-kodierte Signale (`mcBit2*` Methoden).
14+
* **PostdemodulationMixin:** Nachbearbeitung dekodierter Daten (`postDemo_*` Methoden).
15+
* **RSLMixin:** Handler für das RSL-Protokoll.
16+
17+
=== Protokolldefinition (JSON)
18+
Die Datei `sd_protocols/protocols.json` enthält die statischen Definitionen. Jedes Protokoll besitzt eine ID und Eigenschaften wie:
19+
20+
* `format`: Kodierung (z.B. `manchester`, `twostate`, `pwm`).
21+
* `preamble`: Erkennungsmuster.
22+
* `method`: Mapping auf die Python-Methode zur Dekodierung.
23+
24+
=== Parsing Chain (Manchester)
25+
26+
Der Ablauf bei Manchester-Signalen ist wie folgt:
27+
1. **Erkennung:** Match anhand der Preamble/Muster.
28+
2. **Vorvalidierung:** `ManchesterMixin._demodulate_mc_data()` prüft Länge und Taktung.
29+
3. **Dekodierung:** Aufruf der spezifischen `mcBit2*`-Methode.
30+
31+
*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‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
= Beitrag leisten (Contributing)
2+
3+
Beiträge zum Projekt sind willkommen!
4+
5+
== Workflow
6+
7+
1. **Fork & Clone:** Projekt forken und lokal klonen.
8+
2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
9+
3. **Entwicklung:** Änderungen implementieren.
10+
4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
11+
5. **Pull Request:** PR auf GitHub öffnen.
12+
13+
== Tests ausführen
14+
15+
Das Projekt nutzt `pytest`. Stellen Sie sicher, dass `requirements-dev.txt` installiert ist.
16+
17+
[source,bash]
18+
----
19+
pytest
20+
----

‎docs/02_developer_guide/index.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
= Entwickler-Leitfaden
2+
3+
Dieser Abschnitt beschreibt die Architektur, wie man zur Entwicklung beitragen kann (Contributing) und wie man Tests durchführt.
4+
5+
include::architecture.adoc[]
6+
include::contribution.adoc[]

‎docs/03_protocol_reference/index.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
= Protokoll-Referenz
2+
3+
Eine detaillierte Referenz aller unterstützten Protokolle, deren Implementierungsdetails und bekannten Einschränkungen.
4+
5+
include::protocol_details.adoc[]

‎docs/03_protocol_reference/protocol_details.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
= Protokolldetails
2+
3+
PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868 MHz Bereich.
4+
5+
== Protokolldefinition
6+
7+
Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Protokollparameter (Timings, Preambles, Methoden).
8+
9+
== Auszug unterstützter Protokolle
10+
11+
* **ID 10:** Oregon Scientific v2/v3 (Manchester, 433 MHz)
12+
* **ID 13:** Flamingo FA21 Rauchmelder
13+
* **ID 58:** TFA Wettersensoren
14+
* **ID 70:** FHT80TF Tür-/Fensterkontakt (868 MHz)
15+
* **ID 80:** EM1000WZ Energiemonitor
16+
17+
== Protokoll-Typen
18+
19+
* **Manchester:** Selbsttaktend (z.B. Oregon, TFA).
20+
* **TwoState / PWM:** Kodierung über Pulslängen.
21+
* **FSK:** Frequenzumtastung (oft bei 868 MHz Geräten wie Lacrosse).
22+
23+
== Neues Protokoll hinzufügen
24+
25+
1. Definition in `protocols.json` ergänzen.
26+
2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
27+
3. Tests hinzufügen.

‎docs/docinfo.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!-- 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.
2+
3+
BEISPIEL (für Google Search Console Verifizierung):
4+
<meta name="google-site-verification" content="Ihre_Verifizierungs_ID_hier">
5+
6+
BEISPIEL (für benutzerdefinierte Styles):
7+
<link rel="stylesheet" href="custom.css">
8+
-->
9+
10+
<meta name="google-site-verification" content="D0vrv8-mkKHOSvcKXPNS3cVGpYcpEzBL5sFbjfFJ3Rc" />

0 commit comments

Comments
 (0)