Fix sitemap generation and validation

.github/workflows/docs.yml

@@ -87,8 +87,9 @@ jobs:
           path: build/site/html
 
   deploy:
+    if: github.ref == 'refs/heads/main'
     permissions:
-      contents: write 
+      contents: write
       pages: write
       id-token: write
     environment:

README.md

@@ -158,6 +158,16 @@ Beiträge sind willkommen! Bitte erstelle einen Pull‑Request oder öffne ein I
 *   [Protokollreferenz](docs/03_protocol_reference/protocol_details.adoc)
 *   [Befehlsreferenz](docs/01_user_guide/usage.adoc#_command_interface)
 
+## 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 `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 `.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 [Architektur‑Dokument](docs/02_developer_guide/architecture.adoc#dokumentations-infrastruktur-sitemap--seo).
+
 ## Lizenz
 
 Dieses Projekt steht unter der MIT‑Lizenz – siehe [LICENSE](LICENSE) für Details.

requirements.txt

@@ -3,4 +3,5 @@ requests
 paho-mqtt
 python-dotenv
 asyncio-mqtt
-pyserial-asyncio
+pyserial-asyncio
+aiomqtt

sitemap.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" ?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"/>

sitemap_analysis_report.md

@@ -0,0 +1,121 @@
+# Analyse des Sitemap-Generator-Skripts `tools/generate_sitemap.py`
+
+## Zusammenfassung
+
+Das Skript `tools/generate_sitemap.py` generiert eine dynamische `sitemap.xml` basierend auf HTML-Dateien im Build-Output-Ordner. Es weist Prioritäten und Update-Frequenzen basierend auf Dateipfaden zu und unterstützt branch-spezifische Base-URLs.
+
+Die Analyse hat mehrere potenzielle Probleme identifiziert, die zu einer unvollständigen oder fehlerhaften Sitemap führen können.
+
+## 1. Generierungsprozess
+
+### Wie werden HTML-Dateien gefunden?
+- Die Funktion `scan_html_files` durchsucht rekursiv das Build-Verzeichnis (`build_dir`) nach Dateien mit der Endung `.html`.
+- Versteckte Dateien (beginnend mit `_` oder `.`) werden ignoriert.
+- Relative Pfade werden vom Build-Verzeichnis aus berechnet.
+
+### Welche Verzeichnisse werden durchsucht?
+- Standardmäßig `build/site/html`. Kann über `--build-dir` angepasst werden.
+- Das Skript erstellt ein minimales Build-Verzeichnis mit Beispiel-HTML, falls das Verzeichnis nicht existiert (Zeilen 355–363). Dies ist ein Test-Fallback, der in Produktion nicht auftreten sollte.
+
+### Wie werden URLs konstruiert?
+- Basis-URL wird aus `--base-url` oder Branch-Mapping (`BRANCH_URLS`) bestimmt.
+- Für jede HTML-Datei:
+  - Wenn `rel_path == 'index.html'` → `url_path = ''`
+  - Wenn `rel_path.endswith('/index.html')` → `url_path = rel_path[:-11]` (Entfernt `/index.html`)
+  - Sonst wird `.html`-Endung entfernt (`rel_path[:-5]`)
+- Vollständige URL: `{base_url}/{url_path}` (wenn `url_path` nicht leer)
+
+### Welche Metadaten werden gesetzt?
+- **Priority**: Aus `PRIORITY_MAP` (exakte Übereinstimmung oder Präfix) oder Fallback basierend auf Verzeichnis.
+- **Changefreq**: Aus `CHANGEFREQ_MAP` oder Fallback.
+- **Lastmod**: Git-Änderungsdatum (falls verfügbar), sonst Dateisystem-Modifikationszeit.
+
+## 2. Identifizierte Probleme
+
+### 2.1 Fehlende Build-Verzeichnis-Validierung
+- Das Skript erstellt bei fehlendem Build-Verzeichnis Beispiel-HTML-Dateien (`index.html`, `user-guide/installation.html`). Diese könnten in die Sitemap aufgenommen werden und falsche URLs erzeugen.
+- **Empfehlung**: Statt Beispielen zu erstellen, sollte das Skript mit einem Fehler abbrechen oder zumindest eine klare Warnung ausgeben.
+
+### 2.2 Git-Änderungszeitpunkt unzuverlässig
+- `get_lastmod_for_file` verwendet `cwd=file_path.parent`. Wenn die HTML-Datei außerhalb des Git-Repositories liegt (z.B. im Build-Ordner), schlägt `git log` fehl und es wird die Dateisystem-Modifikationszeit verwendet. Diese kann neuer sein als der tatsächliche Content-Änderungszeitpunkt.
+- **Empfehlung**: Das CWD sollte das Root-Repository sein (`Path.cwd()` oder über `git rev-parse --show-toplevel` ermitteln).
+
+### 2.3 Mapping-Tabellen unvollständig/inkonsistent
+- Die `PRIORITY_MAP` und `CHANGEFREQ_MAP` enthalten Einträge für Dateien, die im aktuellen Test-Build nicht vorhanden sind (z.B. `migration/asyncio-migration.html`, `readme.html`, `changelog.html`, `agents.html`, `devcontainer-environment.html`).
+- Diese Dateien könnten entweder nicht generiert werden oder unter anderen Pfaden liegen. Falls sie fehlen, erhalten sie Fallback-Werte, was nicht unbedingt falsch ist, aber die intendierten Prioritäten/Frequenzen werden nicht angewendet.
+- **Empfehlung**: Mapping-Tabellen mit der tatsächlichen Ausgabe des Dokumentations-Builds abgleichen und ggf. anpassen.
+
+### 2.4 Fehlende Index-HTML-Dateien
+- Im Test-Build fehlen `user-guide/index.html`, `developer-guide/index.html`, `protocol-reference/index.html`. Diese sind in den Mappings enthalten (`priority: 0.8` bzw. `0.7`). Wenn sie nicht generiert werden, fehlen entsprechende Sitemap-Einträge.
+- **Ursache**: Möglicherweise werden diese Index-Dateien nicht von AsciiDoc/Antora erzeugt, weil die entsprechenden `index.adoc`-Dateien existieren. Das Build-System muss überprüft werden.
+- **Empfehlung**: Sicherstellen, dass alle erwarteten HTML-Dateien tatsächlich generiert werden. Andernfalls Mapping-Tabellen bereinigen.
+
+### 2.5 Base-URL für Branches möglicherweise falsch
+- `BRANCH_URLS['main']` ist `https://pysignalduino.rfd-fhem.github.io`. Ist das die korrekte URL für die Hauptdokumentation? Möglicherweise sollte es `https://pysignalduino.github.io` sein.
+- **Empfehlung**: URLs mit den tatsächlichen Deployment-Zielen abgleichen.
+
+### 2.6 Pfadtrenner auf Windows
+- Das Skript verwendet `rel_str = str(rel_path).replace('\\', '/')`. Das ist robust, aber es könnte Probleme geben, wenn Pfade gemischte Schrägstriche enthalten (unwahrscheinlich).
+- Kein kritisches Problem.
+
+### 2.7 Doppelte Slashes in URLs
+- Die Base-URL wird mit `.rstrip('/')` bereinigt. Wenn `url_path` leer ist, wird `full_url = base_url` (ohne trailing slash) korrekt sein. Allerdings erwarten einige Webserver möglicherweise einen trailing slash für die Root-URL. Das ist jedoch kein Sitemap-Problem.
+- **Empfehlung**: Keine Änderung notwendig.
+
+### 2.8 Unvollständige Durchsuchung
+- Das Skript sucht nur nach `.html`-Dateien. Andere Ressourcen (PDF, Bilder) werden ignoriert, was korrekt ist, da Sitemaps typischerweise nur HTML-Seiten enthalten.
+- **Kein Problem**.
+
+### 2.9 Fehlerhafte URL-Konstruktion für "index.html" in Unterverzeichnissen
+- Die Logik `rel_path.endswith('/index.html')` erfasst auch `subdir/index.html`. Das Entfernen von `/index.html` (11 Zeichen) ist korrekt.
+- **Kein Problem**.
+
+## 3. Vergleich mit Dokumentationsstruktur (`docs/`)
+
+### Vorhandene `.adoc`-Dateien:
+- `docs/01_user_guide/index.adoc` → erwartet `user-guide/index.html`
+- `docs/02_developer_guide/index.adoc` → erwartet `developer-guide/index.html`
+- `docs/03_protocol_reference/index.adoc` → erwartet `protocol-reference/index.html`
+- `docs/ASYNCIO_MIGRATION.md` → könnte zu `migration/asyncio-migration.html` werden (wenn konvertiert)
+- `docs/MANCHESTER_MIGRATION.md` → ähnlich
+- `docs/METHODS_MIGRATION_COMPLETE.md` → ähnlich
+- `docs/MIGRATION.md` → ähnlich
+- `docs/SIGNALDUINO_MIGRATION_PLAN.md` → ähnlich
+- `docs/devcontainer_env.md` → `devcontainer-environment.html`
+- `docs/AGENTS.md` (existiert nicht als separate Datei, aber `AGENTS.md` im Root) → `agents.html`
+
+### Diskrepanzen:
+- Viele dieser Migrationsdateien sind `.md`, nicht `.adoc`. Ob sie in HTML umgewandelt werden, hängt vom Build-System ab. Im Test-Build sind sie nicht vorhanden.
+- Die Mapping-Tabellen enthalten Einträge für diese Dateien, aber sie werden möglicherweise nie generiert, was zu fehlenden Sitemap-Einträgen führt.
+
+## 4. Spezifische Probleme, die zur unvollständigen Sitemap führen
+
+1. **Fehlende HTML-Generierung**: Wenn das Build-System nicht alle erwarteten HTML-Dateien erzeugt, fehlen sie in der Sitemap. Das Skript kann nur vorhandene Dateien erfassen.
+
+2. **Falsche Prioritäten/Frequenzen für nicht gemappte Pfade**: Fallback-Logik weist pauschal `priority=0.5` und `changefreq='yearly'` zu, was für bestimmte Seiten unpassend sein könnte.
+
+3. **Git-Lastmod ungenau**: Wenn `git log` fehlschlägt, wird die Dateisystem-Modifikationszeit verwendet, die nicht dem letzten Content-Update entspricht (z.B. bei Neubuild).
+
+4. **Base-URL-Konfiguration**: Wenn die Base-URL falsch ist, sind alle URLs in der Sitemap ungültig.
+
+## 5. Vorschläge zur Behebung
+
+### Kurzfristig (Skript-Anpassungen):
+- **Validierung des Build-Verzeichnisses**: Statt Beispiel-HTML zu erstellen, sollte das Skript einen Fehler ausgeben und den Benutzer auffordern, das Build-Verzeichnis korrekt zu erstellen.
+- **Verbesserte Git-Lastmod**: CWD auf Repository-Root setzen; falls nicht möglich, Fallback auf `git log --all` oder den neuesten Commit, der die Quelldatei (`.adoc`) ändert.
+- **Bereinigung der Mapping-Tabellen**: Entferne Einträge für nicht existierende HTML-Dateien oder passe das Build-System an, damit diese Dateien generiert werden.
+- **Logging verbessern**: Warnung ausgeben, wenn eine Datei in den Mappings nicht gefunden wird.
+
+### Mittelfristig (Build-System-Koordination):
+- **Synchronisation mit Antora/AsciiDoc**: Sicherstellen, dass alle `.adoc`- und `.md`-Dateien in HTML umgewandelt werden und die Pfade mit den Mappings übereinstimmen.
+- **Automatische Generierung der Mapping-Tabellen**: Ein Skript, das die `docs/`-Struktur analysiert und Prioritäten/Frequenzen basierend auf Metadaten (z.B. Frontmatter) zuweist.
+
+### Langfristig (Robustheit):
+- **Integration in CI/CD**: Das Skript sollte nach dem Dokumentations-Build ausgeführt werden, mit korrekter Base-URL je nach Branch.
+- **Validierung der Sitemap**: Nach Generierung sollte die Sitemap auf XML-Konformität und gültige URLs geprüft werden (z.B. mit `validate_sitemap.py`).
+
+## 6. Fazit
+
+Das Sitemap-Generator-Skript ist grundsätzlich funktional, hat jedoch mehrere Schwachstellen, die zu unvollständigen oder fehlerhaften Sitemaps führen können. Die Hauptprobleme liegen in der Diskrepanz zwischen erwarteten und tatsächlich generierten HTML-Dateien sowie in der unzuverlässigen Ermittlung des `lastmod`-Datums.
+
+Durch die oben genannten Vorschläge kann die Zuverlässigkeit und Korrektheit der generierten Sitemap deutlich verbessert werden.

sitemap_validation_report.md

@@ -0,0 +1,115 @@
+# Sitemap-Validierungsbericht
+
+**Datum:** 2025-12-17  
+**Sitemap-URL:** https://rfd-fhem.github.io/PySignalduino/sitemap.xml  
+**Lokale Datei:** `current_sitemap.xml`
+
+## 1. Herunterladen und XML-Struktur
+
+Die Sitemap wurde erfolgreich heruntergeladen (267 Bytes). Die XML-Struktur ist wohlgeformt und entspricht dem Sitemap-Protokoll.
+
+- **XML-Deklaration:** `<?xml version="1.0" ?>` ✓
+- **Root-Element:** `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">` ✓
+- **Namespace:** korrekt ✓
+
+## 2. Inhalt der Sitemap
+
+Die Sitemap enthält **nur einen einzigen URL-Eintrag**:
+
+```xml
+<url>
+  <loc>https://pysignalduino.rfd-fhem.github.io</loc>
+  <lastmod>2025-12-15</lastmod>
+  <changefreq>monthly</changefreq>
+  <priority>1.0</priority>
+</url>
+```
+
+### Validierung der einzelnen Felder:
+- `<loc>`: vorhanden, absolute URL ✓
+- `<lastmod>`: vorhanden, Format YYYY-MM-DD ✓
+- `<changefreq>`: vorhanden, gültiger Wert (`monthly`) ✓
+- `<priority>`: vorhanden, numerischer Wert zwischen 0.0 und 1.0 ✓
+
+**Technisch gesehen ist die Sitemap valide gemäß sitemaps.org.**
+
+## 3. Fehlende Seiten (Vergleich mit erwarteter Dokumentation)
+
+Basierend auf der Projektstruktur (`docs/`) und dem Sitemap-Generierungsskript (`tools/generate_sitemap.py`) werden folgende wichtige Seiten erwartet:
+
+| Kategorie | Erwartete URL (Beispiel) | In Sitemap? |
+|-----------|--------------------------|-------------|
+| Hauptseite | `https://pysignalduino.rfd-fhem.github.io` | ✓ |
+| Benutzerhandbuch | `https://pysignalduino.rfd-fhem.github.io/user-guide/installation` | ✗ |
+| | `https://pysignalduino.rfd-fhem.github.io/user-guide/usage` | ✗ |
+| Entwicklerhandbuch | `https://pysignalduino.rfd-fhem.github.io/developer-guide/architecture` | ✗ |
+| | `https://pysignalduino.rfd-fhem.github.io/developer-guide/contribution` | ✗ |
+| Protokollreferenz | `https://pysignalduino.rfd-fhem.github.io/protocol-reference/protocol-details` | ✗ |
+| Beispiele | `https://pysignalduino.rfd-fhem.github.io/examples/basic-usage` | ✗ |
+| Migrationsdokumente | `https://pysignalduino.rfd-fhem.github.io/migration/asyncio-migration` | ✗ |
+
+**Insgesamt fehlen mindestens 10–15 wichtige Unterseiten.**
+
+## 4. Ursachenanalyse
+
+### 4.1. Basis-URL-Konflikt
+Die Sitemap verwendet die Base-URL `https://pysignalduino.rfd-fhem.github.io`.  
+Ein HTTP-Test ergibt jedoch **HTTP 404** für diese URL, was darauf hindeutet, dass die GitHub Pages-Dokumentation möglicherweise nicht unter dieser Adresse veröffentlicht ist.
+
+Die korrekte Dokumentations-URL könnte stattdessen `https://rfd-fhem.github.io/PySignalduino` sein (wie in der `preview`- und `develop`-Branch-Konfiguration des Skripts). Die Sitemap-Generierung für den `main`-Branch verwendet jedoch die oben genannte URL.
+
+### 4.2. Unvollständige Generierung
+Das Sitemap-Generierungsskript scannt das Build-Verzeichnis (`build/site/html`) nach HTML-Dateien. Wenn dieses Verzeichnis leer ist oder nur `index.html` enthält, wird die Sitemap entsprechend knapp.
+
+Möglicherweise wurde die Dokumentation nicht vollständig gebaut, oder der Build-Prozess hat nicht alle HTML-Dateien erzeugt.
+
+### 4.3. Branch-spezifische Unterschiede
+Laut `BRANCH_URLS` im Skript:
+- `main`: `https://pysignalduino.rfd-fhem.github.io`
+- `preview`: `https://preview.rfd-fhem.github.io/PySignalduino`
+- `develop`: `https://develop.rfd-fhem.github.io/PySignalduino`
+
+Die aktuell gehostete Sitemap stammt vom `main`-Branch, aber die Dokumentation könnte unter einer anderen URL liegen.
+
+## 5. Empfehlungen
+
+1. **Überprüfung der GitHub Pages-Konfiguration:**  
+   Stellen Sie sicher, dass die Dokumentation unter `https://pysignalduino.rfd-fhem.github.io` tatsächlich erreichbar ist. Falls nicht, passen Sie die Base-URL in `BRANCH_URLS` an.
+
+2. **Vollständige Generierung der Sitemap:**  
+   Führen Sie das Sitemap-Generierungsskript mit einem vollständigen Build-Verzeichnis aus, um alle HTML-Dateien zu erfassen:
+   ```bash
+   python3 tools/generate_sitemap.py --build-dir build/site/html --branch main --verbose
+   ```
+
+3. **Validierung der generierten Sitemap:**  
+   Nach der Generierung sollten mindestens 15–20 URL-Einträge enthalten sein (entsprechend der Anzahl der `.adoc`-Dateien).
+
+4. **Automatische Integration in CI/CD:**  
+   Sicherstellen, dass der GitHub Actions Workflow (`.github/workflows/docs.yml`) die Sitemap-Generierung nach jedem Dokumentations-Build ausführt und die `sitemap.xml` korrekt deployt.
+
+5. **Manuelle Ergänzung fehlender URLs:**  
+   Falls bestimmte Seiten absichtlich nicht in der Sitemap erscheinen sollen, prüfen Sie die `PRIORITY_MAP` und `CHANGEFREQ_MAP` im Skript auf Vollständigkeit.
+
+## 6. Zusammenfassung
+
+| Kriterium | Status | Bemerkung |
+|-----------|--------|-----------|
+| XML wohlgeformt | ✓ | Keine Syntaxfehler |
+| Sitemap-Schema konform | ✓ | Korrekte Namespace und Elemente |
+| Anzahl URLs | ❌ | Nur 1 URL (erwartet: >10) |
+| Alle wichtigen Seiten enthalten | ❌ | Fehlen zahlreiche Unterseiten |
+| Absolute URLs | ✓ | `loc` ist absolut |
+| Optionale Felder vorhanden | ✓ | `lastmod`, `changefreq`, `priority` |
+
+**Gesamtbewertung:** Die Sitemap ist **technisch valide, aber inhaltlich unvollständig**. Sie erfüllt nicht den Zweck, Suchmaschinen über die gesamte Dokumentation zu informieren.
+
+## Anhang
+
+- `current_sitemap.xml`: Heruntergeladene Sitemap
+- `test_sitemap.xml`: Beispiel-Sitemap mit erwarteten URLs (generiert mit Test-Build)
+- `validate_sitemap.py`: Validierungsskript
+- `tools/generate_sitemap.py`: Generierungsskript
+
+---
+*Bericht generiert durch automatische Validierung.*