docu_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

Komponente	Technologie
Build-System	Sphinx (Python)
Textformat	reStructuredText (rST) und/oder Markdown (MyST)
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|md}, Fallback auf de. Bilder via localized-figure-Direktive (assets/localized/{lang}/). Glossar aus terms.{lang}.csv (Semikolon-getrennt).

rST/Markdown-Mischbetrieb: Sphinx liest über die Extension MyST-Parser .rst- und .md-Dateien gleichwertig ein. Beide Formate können projektweit gemischt werden (z. B. beschreibung.de.rst neben wartung.de.md im selben Modul) – toctree-Einbindung, Direktiven und die Sprachsuffix-Konvention funktionieren identisch. Pro Modul/Kapitel wird ein einheitliches Format empfohlen, ein Mix ist aber technisch unproblematisch.

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

00_inhaltsverzeichnis     – Inhaltsverzeichnis (wird generiert)
01_zertifikate            – CE/UKCA-Konformität, Konfigurationsbeschreibung,
                            Einbauerklärungen, Komponenten-Konformitätserklärungen
02_sicherheit             – Allgemein, Normen (inkl. gemeinsame/sonstige Spezifikationen),
                            Risikobewertung (inkl. Restrisiken)
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

Kapitel 01_zertifikate und 02_sicherheit wurden um Unterkapitel ergänzt, die von Anhang IV Teil A der VO (EU) 2023/1230 (neue Maschinenverordnung, ersetzt Anhang VII MRL 2006/42/EG) gefordert werden: Einbauerklärungen/Montageanleitungen für eingebaute unvollständige Maschinen, Konformitätserklärungen zugekaufter Komponenten, gemeinsame Spezifikationen, sonstige technische Spezifikationen sowie eine explizite Restrisiken-Section.

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)