# 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, = dieses Repo): 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

| 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)               |


### 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).

Details siehe `doc/Kernkonzepte.md`.

### Kapitelstruktur (`chapters/`)

```text
00_inhaltsverzeichnis     – Inhaltsverzeichnis (wird generiert)
01_zertifikate            – CE/UKCA-Konformität, Konfigurationsbeschreibung
02_sicherheit             – Allgemein, Normen, Risikobewertung
03_anlagenbeschreibung    – Module werden hier via meta.yaml eingefügt
04_betrieb                – Betriebsanleitung
05_wartung                – Wartungsanleitung, Schmierplan
06_steuerung              – Funktionsbeschreibungen pro Steuerungssystem
07_ersatzteile            – Ersatzteillisten
08_lieferantendoku        – Antriebe, Elektrik, Pneumatik, Stahlbau, Sicherheitseinr.
09_technische_unterlagen  – Layouts, Schaltpläne, Notstopp, Bereichsstopp
10_anhang                 – Prüfberichte, Abnahmeprotokolle
```

Details siehe `doc/kapitelstruktur.md`.

### 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`)