diff --git a/doc/Kernkonzepte.md b/doc/Kernkonzepte.md index 52e3969..df6b310 100644 --- a/doc/Kernkonzepte.md +++ b/doc/Kernkonzepte.md @@ -1,5 +1,162 @@ # 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. @@ -220,3 +377,28 @@ Ausgabe: - `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 + +| Phase | Beschreibung | Aufwand | +|-------|---------------------------------------------------------------|-----------| +| 1 | PoC: Ein Modul, ein Kapitel, zwei Sprachen, PDF | 2–3 Tage | +| 2 | Base-Repo aufsetzen: Sphinx, Extensions, LaTeX-CI | 3–5 Tage | +| 3 | Erste 5–10 Module migrieren, Glossar aufbauen | 1–2 Wochen| +| 4 | JSON-Export aus ERP definieren, build.py fertigstellen | 2–3 Tage | +| 5 | Pilotprojekt: Erste vollständige Anlagendokumentation | 1 Woche | +| 6 | CI/CD: Automatischer Build via Gitea Actions oder n8n | 1–2 Tage | + +## 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`)