# Kernkonzepte ## Projektübersicht Sphinx-basiertes Dokumentationssystem für Transport- und Hängefördersysteme. JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten). Zwei-Repo-Architektur: allgemeine Ressourcen (Base-Repo) + projektspezifische Anpassungen (Projekt-Repo). Auftraggeber: Firma Schönenberger Umsetzung: Mista GmbH ## Architektur ### Zwei-Repo-Trennung - **transport-docs-base** (Gitea): Alle wiederverwendbaren Inhalte – Module, Kapitelgerüste, Assets, Glossar, Sphinx-Extensions, LaTeX-Templates, Hilfsskripte. Semver-versioniert (VERSION-Datei). - **projekt-kunde-xyz** (pro Anlage): anlage.json (ERP-Export), projektspezifische Bilder, Overrides, Zusatzkapitel, conf.py, build.py. Das Base-Repo wird beim Build als Mount/Share unter `transport-docs-base/` bereitgestellt. ### Technologie-Stack | Komponente | Technologie | |------------------|--------------------------------------------------| | Build-System | Sphinx (Python) | | Textformat | reStructuredText (rST) | | Templating | Jinja2 (Rahmenkapitel, Titelseite) | | PDF-Erzeugung | LaTeX (pdflatex/lualatex) | | Versionierung | Git (Gitea auf Hetzner) | | Konfiguration | JSON (ERP-Export) + YAML (Modul-Metadaten) | | CI/Automatisierung | Gitea Actions oder n8n | | Bildkonvertierung | ezdxf → SVG, Pillow (Optimierung) | ## Repo-Struktur ### Base-Repo: transport-docs-base ``` transport-docs-base/ ├── conf_base.py # Sphinx-Basiskonfiguration (wird importiert) ├── VERSION # Semver der Dokumentationsbasis ├── _ext/ │ ├── anlagen_builder.py # Hauptextension: JSON → Buchstruktur │ ├── localized_figure.py # Sprachauflösung für Bilder │ └── glossary_loader.py # CSV → Glossar-Direktive ├── _templates/ │ ├── latex/ │ │ ├── preamble.tex # Firmen-CI: Fonts, Farben, Kopfzeilen │ │ ├── titlepage.tex # Titelseite-Template (Jinja2) │ │ └── maketitle.tex │ └── common/ │ └── header_footer.rst ├── assets/ │ ├── shared/ # Sprachneutrale Bilder (~90%) │ │ ├── photos/ │ │ │ ├── weiche_typ_a_foto_01.jpg │ │ │ ├── hubstation_foto_01.jpg │ │ │ └── antrieb_sew_foto_01.jpg │ │ ├── drawings/ # Technische Zeichnungen (DXF → SVG/PDF) │ │ │ ├── weiche_typ_a_layout.svg │ │ │ └── hubstation_schnitt.pdf │ │ ├── symbols/ # ISO 7010 Sicherheitssymbole │ │ │ ├── W001_warnung.svg │ │ │ └── M004_augenschutz.svg │ │ └── diagrams/ # Schaltpläne, Pneumatik │ │ └── stromlaufplan_weiche_a.pdf │ └── localized/ # Sprachspezifische Bilder │ ├── de/ │ │ ├── screenshots/ │ │ │ └── hmi_hauptmenu.png │ │ └── diagramme/ │ │ └── risikograph_weiche_a.svg │ ├── en/ │ │ ├── screenshots/ │ │ │ └── hmi_hauptmenu.png │ │ └── diagramme/ │ │ └── risikograph_weiche_a.svg │ └── fr/ │ └── ... ├── modules/ # Textbausteine pro Maschinentyp │ ├── weiche_typ_a/ │ │ ├── meta.yaml # Abhängigkeiten + Kapitelzuordnung │ │ ├── beschreibung.de.rst │ │ ├── beschreibung.en.rst │ │ ├── risikomatrix.de.rst │ │ ├── risikomatrix.en.rst │ │ ├── wartung.de.rst │ │ └── images/ │ │ └── montage_detail_01.jpg │ ├── hubstation/ │ │ ├── meta.yaml │ │ ├── beschreibung.de.rst │ │ ├── technische_daten.de.rst │ │ ├── wartung.de.rst │ │ └── images/ │ │ └── hubmechanik_detail.jpg │ ├── antrieb_sew/ │ │ ├── meta.yaml │ │ └── ... │ └── steuerung_siemens_s7/ │ ├── meta.yaml │ └── ... ├── chapters/ # Rahmenkapitel (Gerüst) │ ├── 01_einleitung/ │ │ ├── template.de.rst # Jinja2-Template mit Platzhaltern │ │ └── template.en.rst │ ├── 02_sicherheit/ │ │ ├── allgemein.de.rst # Immer dabei │ │ ├── allgemein.en.rst │ │ ├── normen_ce.de.rst # EU-Konformität │ │ └── normen_ukca.en.rst # UK-spezifisch │ ├── 03_anlagenbeschreibung/ │ │ └── template.de.rst # Hier werden Module eingefügt │ ├── 04_betrieb/ │ │ └── template.de.rst │ ├── 05_wartung/ │ │ ├── allgemein.de.rst │ │ └── schmierplan_template.de.rst │ ├── 06_ersatzteile/ │ │ └── template.de.rst │ └── 07_anhang/ │ └── template.de.rst ├── glossary/ │ ├── terms.de.csv # "Begriff;Definition;Kategorie" │ ├── terms.en.csv │ └── terms.fr.csv ├── styles/ │ ├── firma_logo.pdf │ ├── firma_logo_sw.pdf │ └── color_scheme.yaml # CI-Farben für LaTeX und SVG ├── scripts/ │ ├── dxf2svg.py # DXF → SVG Konvertierung │ ├── optimize_images.py # Bildoptimierung vor Commit │ └── validate_modules.py # Prüft meta.yaml Konsistenz ``` ### Projekt-Repo: projekt-kunde-xyz ``` projekt-kunde-xyz-2026/ ├── conf.py # Importiert conf_base.py vom Base-Repo ├── anlage.json # ERP-Export: Maschinenauswahl + Metadaten ├── build.py # Hauptbuild-Skript ├── Makefile ├── README.md ├── images/ # Projektspezifische Bilder │ ├── aufstellplan_halle3.pdf │ ├── foto_abnahme_01.jpg │ └── kundenlogo.pdf ├── overrides/ # Projektspezifische Überschreibungen │ ├── modules/ │ │ └── weiche_typ_a/ │ │ └── beschreibung.de.rst # Überschreibt Basis wenn vorhanden │ └── chapters/ │ └── 01_einleitung/ │ └── template.de.rst # Kundenspezifische Einleitung ├── additional/ # Kapitel die NUR dieses Projekt hat │ ├── sonderausfuehrung_xyz.de.rst │ └── sonderausfuehrung_xyz.en.rst └── transport-docs-base/ ──────────── # Symlink/Mount zum Base-Repo (Share) ``` ### anlage.json (ERP-Export) Steuert die Zusammenstellung. Enthält Projektmetadaten, Zielsprachen, Normenregion, Liste verbauter Maschinen und Referenzen auf Zusatzkapitel. **Beispiel:** ```json { "projekt": { "nummer": "P-2026-0042", "kunde": "Müller Automotive GmbH", "kunde_logo": "images/kundenlogo.pdf", "standort": "Werk Ingolstadt, Halle 3", "sprachen": ["de", "en"], "normen_region": "EU", "base_version": ">=1.0.0" }, "maschinen": [ { "modul": "weiche_typ_a", "anzahl": 4, "positionen": ["W01", "W02", "W03", "W04"], "variante": "standard" }, { "modul": "hubstation", "anzahl": 2, "positionen": ["H01", "H02"], "variante": "schwerlast", "optionen": ["hydraulisch"] }, { "modul": "antrieb_sew", "anzahl": 12, "positionen": ["A01-A12"] }, { "modul": "steuerung_siemens_s7", "anzahl": 1, "positionen": ["SPS01"], "optionen": ["profinet", "hmi_tp700"] } ], "zusatz_kapitel": [ "additional/sonderausfuehrung_xyz" ] } ``` ### meta.yaml (Modul-Metadaten) Pro Maschinentyp-Modul. Definiert Bezeichner, mehrsprachigen Namen, Kapitelzuordnung, Bildreferenzen und Abhängigkeiten. **Beispiel** (`modules/weiche_typ_a/meta.yaml`): ```yaml module: weiche_typ_a display_name: de: "Weiche Typ A" en: "Switch Type A" chapters: - 02_sicherheit: sections: [risikomatrix] - 03_anlagenbeschreibung: sections: [beschreibung, technische_daten] - 05_wartung: sections: [wartung, schmierplan] images: shared: - photos/weiche_typ_a_foto_01.jpg - drawings/weiche_typ_a_layout.svg - diagrams/stromlaufplan_weiche_a.pdf localized: - diagramme/risikograph_weiche_a.svg - screenshots/hmi_hauptmenu.png module_local: - montage_detail_01.jpg requires: - antrieb_sew ``` ### conf.py (Projekt-Konfiguration) Importiert die Basiskonfiguration vom gemounteten Base-Repo und setzt projektspezifische Overrides. **Beispiel** (`projekt-kunde-xyz-2026/conf.py`): ```python import sys import os from pathlib import Path # ══ Pfad zum Base-Repo (Share/Mount) ══ BASE_DOCS = Path(os.environ.get( "DOCS_BASE_PATH", Path(__file__).parent / "transport-docs-base" )) # Extensions und Basiskonfiguration importieren sys.path.insert(0, str(BASE_DOCS / "_ext")) sys.path.insert(0, str(BASE_DOCS)) from conf_base import * # noqa: F401, F403 # ══ Projektspezifische Overrides ══ project = "Anlagendokumentation P-2026-0042" release = "1.0" author = "Mista GmbH" copyright = "2026, Mista GmbH" # Bildpfade: Projekt → Overrides → Base (Reihenfolge = Priorität) image_search_path = [ "images", # Projektbilder "overrides", # Überschreibungen str(BASE_DOCS / "assets" / "shared"), # Sprachneutrale Basis str(BASE_DOCS / "assets" / "localized"), # Sprachspezifische Basis str(BASE_DOCS / "modules"), # Modulbilder ] # Sphinx-Extensions aus Base-Repo laden extensions += [ "anlagen_builder", "localized_figure", "glossary_loader", ] # Glossar-Pfad glossary_csv_path = str(BASE_DOCS / "glossary") # LaTeX-Templates aus Base-Repo templates_path.insert(0, str(BASE_DOCS / "_templates")) # LaTeX-spezifisch latex_elements = { "preamble": open(BASE_DOCS / "_templates" / "latex" / "preamble.tex").read(), "maketitle": open(BASE_DOCS / "_templates" / "latex" / "maketitle.tex").read(), "papersize": "a4paper", "pointsize": "11pt", } ``` ### Override-Mechanismus Suchreihenfolge beim Build: 1. `projekt/overrides/` (projektspezifisch) 2. `transport-docs-base/modules/` bzw. `chapters/` (allgemein) Ermöglicht kundenspezifische Anpassungen ohne Base-Repo-Änderung. ### Versionskontrolle Base-Repo hat Semver in `VERSION`. Projekt-Repo kann `"base_version": ">=2.1.0"` in anlage.json setzen. build.py prüft Kompatibilität vor dem Build. ## Mehrsprachigkeit ### Drei Ebenen 1. **Textbausteine**: Dateinamenskonvention `{name}.{lang}.rst`. Fallback auf `de` bei fehlender Übersetzung. 2. **Bilder**: `localized-figure`-Direktive löst `assets/localized/{lang}/pfad/bild.png` auf. Fallback auf `de`. Optional: Jinja2-SVG-Templates für Diagramme mit Text. 3. **Glossar**: CSV pro Sprache (`terms.{lang}.csv`), `glossary_loader.py` erzeugt Sphinx-Glossardirektiven. Im Text via `:term:`Fachbegriff`` verlinkt. ### Sprachspezifische Normen Gesteuert über `normen_region` in anlage.json. Kapitel 02_sicherheit enthält z.B. `normen_ce.de.rst` (EU) und `normen_ukca.en.rst` (UK), Build wählt nach Region. ## Bildverwaltung | Kategorie | Pfad | Beispiele | |------------------|-----------------------------------|----------------------------------------------| | Sprachneutral | `assets/shared/{typ}/` | Fotos, DXF/SVG-Zeichnungen, ISO-Symbole | | Sprachspezifisch | `assets/localized/{lang}/{typ}/` | HMI-Screenshots, Risikographen, Typenschilder| | Modulspezifisch | `modules/{modul}/images/` | Montagedetails | | Projektspezifisch| `projekt/images/` | Aufstellpläne, Abnahmefotos, Kundenlogo | Formate: SVG/PDF für Zeichnungen (vektoriell), JPG für Fotos (max 2000px, 85% Qualität). ## Build-Prozess ``` anlage.json ──→ build.py │ ├─ Phase 1: Konfiguration einlesen, Versionscheck ├─ Phase 2: Abhängigkeiten auflösen (meta.yaml, transitiv) │ Overrides anwenden (Projekt > Base) │ Fehlende Module/Bilder/Übersetzungen melden ├─ Phase 3: Sphinx-Quellen generieren (index.rst, toctrees) │ Glossar aus CSV erzeugen │ Jinja2-Templates mit Projektdaten füllen └─ Phase 4: sphinx-build -b latex → pdflatex → PDF (pro Sprache) Ausgabe: _output/P-2026-0042_Dokumentation_DE.pdf _output/P-2026-0042_Documentation_EN.pdf ``` ## Sphinx-Extensions (zu implementieren) ### anlagen_builder.py - Liest anlage.json + meta.yaml aller referenzierten Module - Löst Abhängigkeiten auf (topologisch, transitiv) - Generiert toctree-Einträge pro Kapitel - Wendet Override-Logik an ### localized_figure.py - Neue Direktive `.. localized-figure::` - Löst Bildpfad nach Build-Sprache auf - Fallback: `de` wenn Sprachversion fehlt ### glossary_loader.py - Liest `terms.{lang}.csv` (Semikolon-getrennt) - Erzeugt `.. glossary::` Blöcke - Ermöglicht `:term:` Verlinkung im gesamten Dokument ## Hilfsskripte - `scripts/dxf2svg.py` – DXF → SVG Konvertierung (ezdxf) - `scripts/optimize_images.py` – Bildoptimierung vor Commit (Pillow, max 2000px) - `scripts/validate_modules.py` – Prüft meta.yaml-Konsistenz, fehlende Dateien/Übersetzungen ## Infrastruktur - Hetzner-Server: Gitea (Repos), n8n (CI-Automatisierung), Nextcloud (Dateiablage) - Build-Umgebung: Python 3.11+, Sphinx, LaTeX-Distribution (texlive) - CI: Gitea Actions oder n8n-Webhook → Build → PDF nach Nextcloud ## Umsetzungsphasen ### Methodik (nach Alistair Cockburn) Jeder Use Case durchläuft sieben Schritte bis zur Umsetzungsreife: | Schritt | Aktivität | Verantwortung | |---------|--------------------------------------------------------|---------------| | 1 | Titel / Teaser, Prosa-Story | C (Kunde/PO) | | 2 | Stakeholder & Interessen / Anwender-Ziele identifizieren | T (Dev Team) | | 3 | Standard-Ablauf entwerfen (primäres Erfolgsszenario) | M (Member) | | 4 | Ausnahmen und Erweiterungen sammeln | T (Dev Team) | | 5 | Ausnahmen detaillieren, Schneiden in User Stories | M (Member) | | 6 | Business Value schätzen / Aufwand schätzen | T (Dev Team) | | 7 | Review: Prüfe alle Interessen, Definition of Ready | C (Kunde/PO) | **Legende Verantwortung:** - **C** = Kunde / Product Owner (N.Sch, M.Ro) - **T** = Dev Team (F.Ve, A.Sch, M.St, D.Fe) - **M** = Einzelnes Dev Team Member ### Personen | Kürzel | Rolle | Schwerpunkt | |--------|------------------------|-----------------------| | N.Sch | Stakeholder / PO | Fachliche Anforderungen | | M.Ro | Stakeholder / PO | Fachliche Anforderungen | | F.Ve | Dev Team | IT und KI | | A.Sch | Dev Team | Redaktion / Inhalte | | M.St | Dev Team | IT und KI | | D.Fe | Dev Team | Redaktion / Inhalte | ### Produktprogramm-Umfang Basis für die Aufwandsschätzung: **1388 eindeutige Produktnummern** in 70 Produktgruppen über 5 Produktfamilien (CPC, GERÜST, ILS 2100, OMNIFLO, Trolleyprogramm). 129 Nummern erscheinen in mehreren Kapiteln. ### Projektplan | Phase | Beschreibung | Aufwand | Beteiligte | |-------|--------------|---------|------------| | 0 | **Use-Case-Definition & Anforderungen** | | | | 0.1 | Story & Teaser: Zieldokumentation beschreiben, Prosa-Story je Produktfamilie | 2 Tage | D.Fe, A.Sch, M.St | | 0.2 | Stakeholder-Analyse: Alle Akteure und deren Interessen/Ziele auflisten | 1 Tag | F.Ve, A.Sch, M.St, D.Fe | | 0.3 | Standard-Ablauf entwerfen: Build-Pipeline, Redaktionsworkflow, Freigabeprozess | 2 Tage | M.St | | 0.4 | Ausnahmen sammeln: Sonderfälle (Mehrfachverwendung der 129 Nummern, Varianten, fehlende Übersetzungen) | 1 Tag | F.Ve, A.Sch, M.St, D.Fe | | 0.5 | Ausnahmen detaillieren, in User Stories schneiden | 2 Tage | F.Ve, M.St | | 0.6 | Aufwandsschätzung & Business Value für alle Stories | 1 Tag | F.Ve, A.Sch, M.St, D.Fe | | 0.7 | Review & DOR: Prüfung aller Interessen, Freigabe für Umsetzung | 1 Tag | N.Sch, M.Ro | | | | | | | 1 | **PoC: Proof of Concept** | | | | 1.1 | Ein Modul (z.B. OMNIFLO Weiche), ein Kapitel, zwei Sprachen (DE/EN), PDF-Ausgabe | 3 Tage | M.St, F.Ve | | 1.2 | LaTeX-Template mit Firmen-CI erstellen und validieren | 2 Tage | M.St, F.Ve, A.Sch | | 1.3 | PoC-Review mit Stakeholdern | 0,5 Tage | N.Sch, M.Ro, A.Sch | | | | | | | 2 | **Base-Repo & Infrastruktur** | | | | 2.1 | Repo-Struktur anlegen (transport-docs-base), Sphinx-Projekt initialisieren | 1 Tag | M.St | | 2.2 | Sphinx-Extensions implementieren (anlagen_builder, localized_figure, glossary_loader) | 4 Tage | M.St | | 2.3 | build.py: JSON-Parsing, Abhängigkeitsauflösung, Override-Mechanismus | 3 Tage | F.Ve, M.St | | 2.4 | CI/CD: Gitea Actions für automatischen Build | 2 Tage | M.St | | | | | | | 3 | **Produktprogramm-Strukturierung** | | | | 3.1 | Modulstruktur & meta.yaml-Schema je Produktfamilie definieren (5 Familien) | 3 Tage | A.Sch, M.St, D.Fe | | 3.2 | Nummernkreis-Mapping: 1388 Produkte auf Module abbilden, Gruppierung festlegen | 3 Tage | A.Sch, F.Ve, M.St | | 3.3 | Vorlage-Templates pro Kapiteltyp erstellen (Beschreibung, Wartung, Ersatzteile) | 2 Tage | A.Sch, M.St | | | | | | | 4 | **Content-Migration (Hauptaufwand)** | | | | 4.1 | CPC-Familie: 126 Produkte in 11 Gruppen – rST-Bausteine erstellen | 2 Wochen | A.Sch, F.Ve | | 4.2 | GERÜST-Familie: 263 Produkte in 14 Gruppen – rST-Bausteine erstellen | 1 Wochen | A.Sch, F.Ve | | 4.3 | ILS 2100-Familie: 396 Produkte in 27 Gruppen – rST-Bausteine erstellen | 3 Wochen | A.Sch, F.Ve | | 4.4 | OMNIFLO-Familie: 453 Produkte in 14 Gruppen – rST-Bausteine erstellen | 4 Wochen | A.Sch, F.Ve | | 4.5 | Trolleyprogramm: 191 Produkte in 4 Gruppen – rST-Bausteine erstellen | 2 Wochen | A.Sch, F.Ve | | 4.6 | KI-gestützte Textgenerierung: Vorlagen automatisiert befüllen (Beschreibungen, techn. Daten, Logische Schalter) | parallel | F.Ve, M.St | | 4.7 | Bildmaterial: Fotos/Zeichnungen zuordnen, optimieren, Pfadstruktur aufbauen | parallel | A.Sch, F.Ve | | | | | | | 5 | **Glossar & Mehrsprachigkeit** | | | | 5.1 | Glossar DE aufbauen (Fachbegriffe aus allen 5 Produktfamilien) | 1 Woche | A.Sch, D.Fe, M.St | | 5.2 | Glossar EN übersetzen | 1 Woche | A.Sch, D.Fe, M.St, V.Fe | | 5.3 | Stichproben-Übersetzung: 10% der Module auf EN migrieren | 2 Wochen | A.Sch, D.Fe, F.Ve | | | | | | | 6 | **ERP-Integration & Automatisierung** | | | | 6.1 | JSON-Export-Format mit ERP abstimmen (anlage.json-Schema) | 2 Tage | M.St, A.Jakob | | 6.2 | Validierungsskripte: meta.yaml-Konsistenz, fehlende Dateien/Übersetzungen | 2 Tage | M.St | | 6.3 | Hilfsskripte: dxf2svg, optimize_images | 2 Tage | F.Ve | | | | | | | 7 | **Pilotprojekt** | | | | 7.1 | Erste vollständige Anlagendokumentation (reales Kundenprojekt) generieren | 1 Woche | A.Sch, M.St, F.Ve | | 7.2 | Review mit Stakeholdern, Korrekturrunde | 3 Tage | N.Sch, M.Ro, A.Sch | | 7.3 | Lessons Learned, Backlog-Pflege | 1 Tag | F.Ve, A.Sch, M.St, D.Fe | ### Aufwandszusammenfassung | Phase | Dauer (geschätzt) | |-------|-------------------| | 0 – Use-Case-Definition | ~2 Wochen | | 1 – PoC | ~1 Woche | | 2 – Base-Repo & Infrastruktur | ~2 Wochen | | 3 – Produktprogramm-Strukturierung | ~2 Wochen | | 4 – Content-Migration | ~10-12 Wochen (2 Redakteure parallel + KI-Unterstützung) | | 5 – Glossar & Mehrsprachigkeit | ~4 Wochen | | 6 – ERP-Integration | ~1 Woche | | 7 – Pilotprojekt | ~2 Wochen | | **Gesamt** | **~24 Wochen (6 Monate)** | **Anmerkungen:** - Phase 4 ist der Hauptaufwand. Bei 1388 Produkten und 2 Redakteurinnen (A.Sch, F.Ve) parallel ergibt sich ca. 10 Wochen netto für die Content-Erstellung. - KI-gestützte Textgenerierung (F.Ve, M.St) kann den Aufwand in Phase 4 um geschätzt 30–50% reduzieren. - Phasen 4, 5 und 6 können teilweise parallelisiert werden, wodurch die Gesamtlaufzeit auf ca. 5 Monate verkürzt werden kann. - Die Schätzung basiert auf ~20 Produkte/Woche pro Redakteur bei mittlerer Komplexität (Beschreibung, techn. Daten, Wartungshinweise als rST-Bausteine). ## Coding-Konventionen - Python: Type Hints, Docstrings, pyright-kompatibel - rST: Eine Datei pro Section, Dateiname = Section-Slug - YAML: 2 Spaces Einrückung, keine Tabs - Commits: Conventional Commits (`feat:`, `fix:`, `docs:`) - Bilder: Dateinamen lowercase, Underscores, beschreibend (`weiche_typ_a_foto_01.jpg`)