71 lines
3.7 KiB
Markdown
71 lines
3.7 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): 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`)
|