101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
# 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`)
|