[[01 Home Assistant|← Zurück zu Home Assistant]] # Word-Export: Home Assistant Systemdokumentation Erzeugt `Home-Assistant-Systemdokumentation.docx` – eine zusammenfassende Projektdokumentation der Smart-Home-Installation. Die `.docx` ist **bewusst nicht eingecheckt**, sie lässt sich jederzeit neu erzeugen. > [!important] Quelle ist EINE Notiz, keine Zusammenstellung > Anders als bei [[00-Start|CooleSenioren]] (dort fügt `build_cs.py` 13 Notizen aneinander) > ist die Quelle hier **eine redaktionell geschriebene Zusammenfassung**: > [[02 HA-Systemdokumentation]]. Grund: Aus 6.586 Wörtern Rohmaterial (≈ 19 Seiten) sollten > 5–10 Seiten werden – das ist eine **Verdichtung**, keine Zusammenstellung, und die kann > kein Skript leisten. Die 16 Einzelnotizen bleiben die Detailebene und werden **nicht** > exportiert. > > **Konsequenz:** Ändert sich eine Detailnotiz inhaltlich, muss die Zusammenfassung von Hand > nachgezogen werden. Diese Doppelpflege ist der Preis der Zusammenfassung. ## Zweck und Zuschnitt (Nutzervorgaben vom 17.07.2026) | Vorgabe | Umsetzung | |---|---| | **Zweck: Vorzeigen** | Fokus auf Architektur, Leistungsumfang und gelöste Probleme statt auf Kommandos | | **Umfang: 5–10 Seiten** | ~1.760 Wörter + 6 Tabellen → ca. 8 Seiten inkl. Titelseite und Verzeichnis | | **Scope: nur dieser Ordner** | Batteriespeicher/Omnibattery erhält eine **eigene** Dokumentation und ist hier nur als Systemgrenze erwähnt | | **Generisches weglassen** | Zigbee-Theorie, allgemeine Sensortypen und Beispiel-YAML mit Platzhalter-Entitäten sind **nicht** im Export – sie beschreiben nicht diese Anlage | ## Aufruf ```bash # 1) Zwischenstufe bauen -> _build/out/ha-systemdoku.md PYTHONIOENCODING=utf-8 python "20 Software/Home Assistant/_build/build_ha.py" # 2) Word erzeugen "/c/Program Files/Pandoc/pandoc" "20 Software/Home Assistant/_build/out/ha-systemdoku.md" \ -o "20 Software/Home Assistant/Home-Assistant-Systemdokumentation.docx" \ --reference-doc="40 Projekte/CooleSenioren/_build/reference-footer.docx" \ --toc \ --metadata title="Home Assistant" \ --metadata subtitle="Systemdokumentation der Smart-Home-Installation" \ --metadata author="Joachim Berger" \ --metadata date="Stand: 17.07.2026" \ --metadata lang="de-DE" \ --metadata toc-title="Inhaltsverzeichnis" # 3) Titelseite/Verzeichnis zurechtrücken (Pflichtschritt, siehe unten) PYTHONIOENCODING=utf-8 python "20 Software/Home Assistant/_build/layout_ha.py" \ "20 Software/Home Assistant/Home-Assistant-Systemdokumentation.docx" # 4) Dokumenteigenschaften setzen (Pflichtschritt) PYTHONIOENCODING=utf-8 python "40 Projekte/CooleSenioren/_build/set_props.py" \ "20 Software/Home Assistant/Home-Assistant-Systemdokumentation.docx" ``` > [!warning] Word muss die Zieldatei geschlossen haben > Sonst bricht Pandoc mit `permission denied` ab. `layout_ha.py` und `set_props.py` prüfen > die Lockdatei `~$...docx` selbst und brechen sauber ab, statt eine halbfertige > `.tmp.docx` zu hinterlassen. ## Wiederverwendung aus CooleSenioren Zwei Bausteine liegen unter `40 Projekte/CooleSenioren/_build/`, sind aber **nicht projektspezifisch** – sie liegen dort nur historisch, weil sie dort entstanden sind: | Baustein | Was es tut | |---|---| | `reference-footer.docx` | Obeco-Firmenvorlage: A4, Fußzeile mit Logo links und „Seite X von Y" mittig | | `set_props.py` | Setzt Titel, Thema, Stichwörter, Kategorie, **Firma „Obeco GmbH"**; entfernt die aus der Pandoc-Vorlage geerbten Falschangaben | Beide werden hier **wiederverwendet statt kopiert** – eine Kopie müsste doppelt gepflegt werden. `set_props.py` kennt die HA-Datei über einen eigenen Eintrag in `PROPS` (mit abweichendem Thema/Kategorie: „Systemdokumentation"/„Dokumentation" statt „Konzept"). > [!note] Offene Aufräumarbeit > Sauber wäre ein neutraler Ort für beide Bausteine (z. B. `90 Vorlagen/_build/`). Das > berührt aber die laufende CooleSenioren-Pipeline, deren `.gitignore`-Ausnahme fest auf > `40 Projekte/CooleSenioren/_build/reference-footer.docx` zeigt. Bewusst verschoben. ## `build_ha.py` – was beim Export passiert | Was | Warum | |---|---| | Nav-Kopfzeile (alles vor der H1) | Vault-Navigation, im Word sinnlos | | Status-Block + Änderungshistorie + Footer | interne Arbeitsstände | | Zeilen `→ Details: …` | verweisen auf die Einzelnotizen, die nicht mitexportiert werden – im Word zeigten sie ins Leere | | Wikilinks `[[Ziel\|Label]]` | zu `Label` bzw. `Ziel` aufgelöst | | **H1 entfernt, alle Ebenen hochgestuft** | Der Titel steht schon auf der Titelseite. Bliebe die H1, wäre sie ein redundanter erster Verzeichnis-Eintrag. Nach dem Hochstufen bilden die 8 Kapitel die oberste Ebene. Die **Notiz im Vault behält ihre H1** – nur der Export wird umgebaut. | ### Eingebaute Prüfungen Das Skript bricht **hart ab**, statt eine kaputte Datei zu erzeugen: - Notiz ohne H1 oder ohne Status-Block (Struktur unerwartet) - Wikilink-Reste, Status/Historie oder `→ Details:`-Zeilen im Ergebnis - Keine Kapitel-Überschrift vorhanden (Hochstufen fehlgeschlagen) - Wortzahl außerhalb **1.400–3.800** – entspricht grob dem Zielkorridor 5–10 Seiten (Tabellen brauchen mehr Platz als Fließtext, die untere Grenze ist deshalb großzügig) ## `layout_ha.py` – warum ein Extraschritt nötig ist Pandoc setzt das `--toc`-Verzeichnis **fest** zwischen Titelblock und Fließtext. Der Firmen-Adressblock ist aber Teil des Body-Textes (als rohes OpenXML – **nicht** als `author`-Metadatum, das würde `dc:creator` verseuchen). Ohne diesen Schritt landet die Adresse also **hinter** dem Verzeichnis: ``` Titel | Untertitel | Verfasser | Datum | INHALTSVERZEICHNIS | Adresse | Text ^^^^^^^ falsch ``` Zusätzlich setzt Pandoc **keine Seitenumbrüche** – Titelseite, Verzeichnis und Text klebten aneinander. `layout_ha.py` zieht die zwei Adress-Absätze vor den `<w:sdt>`-Block und setzt je einen Umbruch dahinter: ``` Titel | Untertitel | Verfasser | Datum | Adresse ---- Seitenumbruch ---- Inhaltsverzeichnis ---- Seitenumbruch ---- Text ``` Das Skript ist **nicht idempotent**: Ein zweiter Lauf bricht ab, weil der Adressblock dann schon vorn steht. Es identifiziert die Adresszeilen über ihren **Text**, nicht über den Stil – der Verfasser „Joachim Berger" trägt denselben `Author`-Stil. > [!tip] Gegenprobe im XML, nicht per Textextraktion > `pandoc datei.docx -t plain` zeigt die Adresse **nicht** – Pandoc liest `Author`-Absätze > beim Rücklesen wieder als Metadaten. Kein Fehler: in `word/document.xml` prüfen. --- **Status:** In Bearbeitung **Version:** 1.0 **Letzte Aktualisierung:** 17.07.2026 10:35 Uhr ### Änderungshistorie | Version | Datum | Uhrzeit | Änderung | |---|---|---|---| | 1.0 | 17.07.2026 | 10:35 | Erstfassung – Pipeline für die HA-Systemdokumentation (Nutzervorgabe: Word wie bei CooleSenioren, 5–10 Seiten, Zweck „Vorzeigen"). Quelle ist bewusst **eine** redaktionelle Zusammenfassung statt einer Notiz-Zusammenstellung. Vorlage und `set_props.py` aus CooleSenioren wiederverwendet. Beim Bauen entdeckt und behoben: Adressblock landete hinter dem Inhaltsverzeichnis (fiel bei CooleSenioren nie auf, weil `place_toc.py` das Verzeichnis dort ohnehin wegschiebt), Pandoc setzte keine Seitenumbrüche, und die H1 wiederholte den Titel der Titelseite | --- [[Impressum|Impressum]] | [[Datenschutzerklärung|Datenschutz]]