Erste Fassung erstellt.

2026-04-28 17:51:52 +02:00
commit 200a482c32
35 changed files with 1027 additions and 0 deletions
@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Projektübersicht
+
+Sphinx-basiertes Dokumentationssystem für Transport- und Hängefördersysteme (Firma Schönenberger, umgesetzt von Mista GmbH). JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten). Projekt befindet sich in der Planungs-/Aufbauphase – die Sphinx-Extensions und der Build-Prozess sind noch zu implementieren.
+
+## Entwicklungsumgebung
+
+```bash
+# Setup (einmalig)
+bin/install_py.bat          # Windows
+bash bin/install_py.sh      # Linux
+
+# Umgebung aktivieren
+bin/activate_venv.bat       # Windows
+source bin/activate_venv.sh # Linux
+
+# Shell mit gesetzten Umgebungsvariablen
+bin/get_cmd.bat             # Windows
+source bin/get_cmd.sh       # Linux
+```
+
+Python-Code kommt nach `lib/`, Konfiguration nach `cfg/`. Die `bin/`-Skripte setzen Umgebungsvariablen (`PROJECT`, `PV_BIN`, `PV_LIB`, `PV_CFG`, `PV_DATA`, `PV_LOG`, `PV_RESULTS`, `PV_EXAMPLES`) und erweitern `PYTHONPATH` um `PV_LIB`.
+
+## Architektur: Zwei-Repo-System
+
+Dieses Repo (`docu_build`) dient als Entwicklungs- und Planungsumgebung. Das Zielsystem besteht aus zwei getrennten Repos:
+
+- **transport-docs-base** (Gitea): Wiederverwendbare Inhalte – Sphinx-Extensions (`_ext/`), Module (`modules/`), Kapitelgerüste (`chapters/`), Assets, Glossar, LaTeX-Templates. Semver-versioniert via `VERSION`-Datei.
+- **projekt-kunde-xyz** (pro Anlage): `anlage.json` (ERP-Export), projektspezifische Bilder, Overrides, `conf.py`, `build.py`. Bindet Base-Repo als `transport-docs-base/` ein (Symlink/Mount).
+
+### Technologie-Stack
+
+Sphinx + reStructuredText + Jinja2-Templating → LaTeX → PDF. Konfiguration via JSON (ERP-Export) + YAML (Modul-Metadaten). Bildkonvertierung: ezdxf → SVG, Pillow. CI: Gitea Actions oder n8n auf Hetzner-Server.
+
+### Build-Pipeline (zu implementieren)
+
+`anlage.json` → `build.py` → Versionscheck → Abhängigkeiten auflösen (meta.yaml) → Overrides anwenden → Sphinx-Quellen generieren → `sphinx-build -b latex` → pdflatex → PDF pro Sprache. Ausgabe: `_output/P-XXXX_Dokumentation_DE.pdf`.
+
+### Kernmechanismen
+
+**Override-Reihenfolge**: `projekt/overrides/` > `transport-docs-base/modules/` bzw. `chapters/`
+
+**Mehrsprachigkeit**: Dateinamenskonvention `{name}.{lang}.rst`, Fallback auf `de`. Bilder via `localized-figure`-Direktive (`assets/localized/{lang}/`). Glossar aus `terms.{lang}.csv` (Semikolon-getrennt).
+
+**anlage.json**: Steuert Zusammenstellung – enthält `projekt` (Metadaten, Sprachen, Normenregion), `maschinen` (Modulliste mit Positionen/Varianten/Optionen), `zusatz_kapitel`.
+
+**meta.yaml** (pro Modul): Definiert `display_name` (mehrsprachig), `chapters` (Kapitelzuordnung mit Sections), `images` (shared/localized/module_local), `requires` (Abhängigkeiten).
+
+### Sphinx-Extensions (zu implementieren in `_ext/`)
+
+- **anlagen_builder.py**: JSON + meta.yaml → toctree-Einträge, Abhängigkeitsauflösung (topologisch), Override-Logik
+- **localized_figure.py**: Direktive `.. localized-figure::` – Bildpfad nach Sprache auflösen, Fallback `de`
+- **glossary_loader.py**: CSV → `.. glossary::` Blöcke, ermöglicht `:term:` Verlinkung
+
+### Hilfsskripte (zu implementieren in `scripts/`)
+
+- `dxf2svg.py` – DXF → SVG (ezdxf)
+- `optimize_images.py` – Bildoptimierung (Pillow, max 2000px, 85% JPG)
+- `validate_modules.py` – meta.yaml-Konsistenzprüfung
+
+## 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`)