|
| 1 | +# Analyse des Sitemap-Generator-Skripts `tools/generate_sitemap.py` |
| 2 | + |
| 3 | +## Zusammenfassung |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +Die Analyse hat mehrere potenzielle Probleme identifiziert, die zu einer unvollständigen oder fehlerhaften Sitemap führen können. |
| 8 | + |
| 9 | +## 1. Generierungsprozess |
| 10 | + |
| 11 | +### Wie werden HTML-Dateien gefunden? |
| 12 | +- Die Funktion `scan_html_files` durchsucht rekursiv das Build-Verzeichnis (`build_dir`) nach Dateien mit der Endung `.html`. |
| 13 | +- Versteckte Dateien (beginnend mit `_` oder `.`) werden ignoriert. |
| 14 | +- Relative Pfade werden vom Build-Verzeichnis aus berechnet. |
| 15 | + |
| 16 | +### Welche Verzeichnisse werden durchsucht? |
| 17 | +- Standardmäßig `build/site/html`. Kann über `--build-dir` angepasst werden. |
| 18 | +- 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. |
| 19 | + |
| 20 | +### Wie werden URLs konstruiert? |
| 21 | +- Basis-URL wird aus `--base-url` oder Branch-Mapping (`BRANCH_URLS`) bestimmt. |
| 22 | +- Für jede HTML-Datei: |
| 23 | + - Wenn `rel_path == 'index.html'` → `url_path = ''` |
| 24 | + - Wenn `rel_path.endswith('/index.html')` → `url_path = rel_path[:-11]` (Entfernt `/index.html`) |
| 25 | + - Sonst wird `.html`-Endung entfernt (`rel_path[:-5]`) |
| 26 | +- Vollständige URL: `{base_url}/{url_path}` (wenn `url_path` nicht leer) |
| 27 | + |
| 28 | +### Welche Metadaten werden gesetzt? |
| 29 | +- **Priority**: Aus `PRIORITY_MAP` (exakte Übereinstimmung oder Präfix) oder Fallback basierend auf Verzeichnis. |
| 30 | +- **Changefreq**: Aus `CHANGEFREQ_MAP` oder Fallback. |
| 31 | +- **Lastmod**: Git-Änderungsdatum (falls verfügbar), sonst Dateisystem-Modifikationszeit. |
| 32 | + |
| 33 | +## 2. Identifizierte Probleme |
| 34 | + |
| 35 | +### 2.1 Fehlende Build-Verzeichnis-Validierung |
| 36 | +- 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. |
| 37 | +- **Empfehlung**: Statt Beispielen zu erstellen, sollte das Skript mit einem Fehler abbrechen oder zumindest eine klare Warnung ausgeben. |
| 38 | + |
| 39 | +### 2.2 Git-Änderungszeitpunkt unzuverlässig |
| 40 | +- `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. |
| 41 | +- **Empfehlung**: Das CWD sollte das Root-Repository sein (`Path.cwd()` oder über `git rev-parse --show-toplevel` ermitteln). |
| 42 | + |
| 43 | +### 2.3 Mapping-Tabellen unvollständig/inkonsistent |
| 44 | +- 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`). |
| 45 | +- 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. |
| 46 | +- **Empfehlung**: Mapping-Tabellen mit der tatsächlichen Ausgabe des Dokumentations-Builds abgleichen und ggf. anpassen. |
| 47 | + |
| 48 | +### 2.4 Fehlende Index-HTML-Dateien |
| 49 | +- 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. |
| 50 | +- **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. |
| 51 | +- **Empfehlung**: Sicherstellen, dass alle erwarteten HTML-Dateien tatsächlich generiert werden. Andernfalls Mapping-Tabellen bereinigen. |
| 52 | + |
| 53 | +### 2.5 Base-URL für Branches möglicherweise falsch |
| 54 | +- `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. |
| 55 | +- **Empfehlung**: URLs mit den tatsächlichen Deployment-Zielen abgleichen. |
| 56 | + |
| 57 | +### 2.6 Pfadtrenner auf Windows |
| 58 | +- 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). |
| 59 | +- Kein kritisches Problem. |
| 60 | + |
| 61 | +### 2.7 Doppelte Slashes in URLs |
| 62 | +- 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. |
| 63 | +- **Empfehlung**: Keine Änderung notwendig. |
| 64 | + |
| 65 | +### 2.8 Unvollständige Durchsuchung |
| 66 | +- Das Skript sucht nur nach `.html`-Dateien. Andere Ressourcen (PDF, Bilder) werden ignoriert, was korrekt ist, da Sitemaps typischerweise nur HTML-Seiten enthalten. |
| 67 | +- **Kein Problem**. |
| 68 | + |
| 69 | +### 2.9 Fehlerhafte URL-Konstruktion für "index.html" in Unterverzeichnissen |
| 70 | +- Die Logik `rel_path.endswith('/index.html')` erfasst auch `subdir/index.html`. Das Entfernen von `/index.html` (11 Zeichen) ist korrekt. |
| 71 | +- **Kein Problem**. |
| 72 | + |
| 73 | +## 3. Vergleich mit Dokumentationsstruktur (`docs/`) |
| 74 | + |
| 75 | +### Vorhandene `.adoc`-Dateien: |
| 76 | +- `docs/01_user_guide/index.adoc` → erwartet `user-guide/index.html` |
| 77 | +- `docs/02_developer_guide/index.adoc` → erwartet `developer-guide/index.html` |
| 78 | +- `docs/03_protocol_reference/index.adoc` → erwartet `protocol-reference/index.html` |
| 79 | +- `docs/ASYNCIO_MIGRATION.md` → könnte zu `migration/asyncio-migration.html` werden (wenn konvertiert) |
| 80 | +- `docs/MANCHESTER_MIGRATION.md` → ähnlich |
| 81 | +- `docs/METHODS_MIGRATION_COMPLETE.md` → ähnlich |
| 82 | +- `docs/MIGRATION.md` → ähnlich |
| 83 | +- `docs/SIGNALDUINO_MIGRATION_PLAN.md` → ähnlich |
| 84 | +- `docs/devcontainer_env.md` → `devcontainer-environment.html` |
| 85 | +- `docs/AGENTS.md` (existiert nicht als separate Datei, aber `AGENTS.md` im Root) → `agents.html` |
| 86 | + |
| 87 | +### Diskrepanzen: |
| 88 | +- 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. |
| 89 | +- 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. |
| 90 | + |
| 91 | +## 4. Spezifische Probleme, die zur unvollständigen Sitemap führen |
| 92 | + |
| 93 | +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. |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +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). |
| 98 | + |
| 99 | +4. **Base-URL-Konfiguration**: Wenn die Base-URL falsch ist, sind alle URLs in der Sitemap ungültig. |
| 100 | + |
| 101 | +## 5. Vorschläge zur Behebung |
| 102 | + |
| 103 | +### Kurzfristig (Skript-Anpassungen): |
| 104 | +- **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. |
| 105 | +- **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. |
| 106 | +- **Bereinigung der Mapping-Tabellen**: Entferne Einträge für nicht existierende HTML-Dateien oder passe das Build-System an, damit diese Dateien generiert werden. |
| 107 | +- **Logging verbessern**: Warnung ausgeben, wenn eine Datei in den Mappings nicht gefunden wird. |
| 108 | + |
| 109 | +### Mittelfristig (Build-System-Koordination): |
| 110 | +- **Synchronisation mit Antora/AsciiDoc**: Sicherstellen, dass alle `.adoc`- und `.md`-Dateien in HTML umgewandelt werden und die Pfade mit den Mappings übereinstimmen. |
| 111 | +- **Automatische Generierung der Mapping-Tabellen**: Ein Skript, das die `docs/`-Struktur analysiert und Prioritäten/Frequenzen basierend auf Metadaten (z.B. Frontmatter) zuweist. |
| 112 | + |
| 113 | +### Langfristig (Robustheit): |
| 114 | +- **Integration in CI/CD**: Das Skript sollte nach dem Dokumentations-Build ausgeführt werden, mit korrekter Base-URL je nach Branch. |
| 115 | +- **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`). |
| 116 | + |
| 117 | +## 6. Fazit |
| 118 | + |
| 119 | +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. |
| 120 | + |
| 121 | +Durch die oben genannten Vorschläge kann die Zuverlässigkeit und Korrektheit der generierten Sitemap deutlich verbessert werden. |
0 commit comments