doc_build/CLAUDE.md

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

# 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

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

Kapitelstruktur (chapters/)

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)