Sphinx-basiertes Dokumentationssystem fuer Transport- und Hängeförderanlagen. JSON-gesteuerter Build erzeugt aus modularen Textbausteinen mehrsprachige PDF-Dokumentationen (250+ Seiten). Entwickelt von Mista GmbH fuer Schönenberger.

Das Projekt befindet sich in der Planungs- und Aufbauphase.

Architektur

Das Zielsystem besteht aus zwei Repos:

transport-docs-base (dieses Repo): Wiederverwendbare Inhalte -- Sphinx-Extensions (_ext/), Module (modules/), Kapitelgerüste (chapters/), Assets, Glossar, LaTeX-Templates.
projekt-kunde-xyz (pro Anlage): anlage.json (ERP-Export), projektspezifische Bilder, Overrides, conf.py, build.py. Bindet das Base-Repo per Symlink/Mount ein.

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

Projektstruktur

docu_build/
├── _ext/                   # Sphinx-Extensions (zu implementieren)
├── _templates/             # Sphinx/LaTeX-Templates
├── assets/
│   ├── shared/             # Sprachunabhängige Bilder/Symbole
│   └── localized/          # Sprachspezifische Bilder
├── bin/                    # Skripte zur Umgebungsverwaltung
│   ├── setenv.bat/.sh      # Umgebungsvariablen setzen
│   ├── install_py.bat/.sh  # venv erstellen + pip install
│   ├── activate_venv.bat/.sh # venv aktivieren
│   ├── get_cmd.bat/.sh     # Shell mit Umgebung oeffnen
│   ├── extract_products.*  # Bilder/Text aus Produkt-PDFs extrahieren
│   └── convert_fortna.*    # Fortna-Konvertierung
├── cfg/                    # Konfigurationsdateien
├── chapters/               # Kapitelgerüste (rST)
│   ├── 00_inhaltsverzeichnis/
│   ├── 01_zertifikate/
│   ├── 02_sicherheit/
│   ├── 03_anlagenbeschreibung/
│   ├── 04_betrieb/
│   ├── 05_wartung/
│   ├── 06_steuerung/
│   ├── 07_ersatzteile/
│   ├── 08_lieferantendoku/
│   ├── 09_technische_unterlagen/
│   └── 10_anhang/
├── data/                   # Eingabedaten (nicht im Git)
├── doc/                    # Projektdokumentation
├── glossary/               # Glossar-Quelldaten (CSV)
├── lib/                    # Python-Bibliotheken
├── modules/                # Modulbeschreibungen + meta.yaml
├── scripts/                # Hilfsskripte (dxf2svg, optimize_images, ...)
├── styles/                 # LaTeX-Styles
├── tests/                  # Tests
├── log/                    # Log-Dateien (nicht im Git)
└── results/                # Build-Ausgaben (nicht im Git)

Ein Kundenprojekt enthält nur noch die Verweise auf die verbauten Teile, overrides und additionals, also das Überschreiben von vorhandenen Texten oder Ergänzungen

projekt-kunde-xyz-2026/
├── conf.py                             # Importiert conf_base.py vom Base-Repo
├── anlage.json                         # ERP-Export: Maschinenauswahl + Metadaten
├── build.py                            # Hauptbuild-Skript
├── Makefile
├── README.md
├── images/                             # Projektspezifische Bilder
│   ├── aufstellplan_halle3.pdf
│   ├── foto_abnahme_01.jpg
│   └── kundenlogo.pdf
├── overrides/                          # Projektspezifische Überschreibungen
│   ├── modules/
│   │   └── weiche_typ_a/
│   │       └── beschreibung.de.rst     # Überschreibt Basis wenn vorhanden
│   └── chapters/
│       └── 01_einleitung/
│           └── template.de.rst         # Kundenspezifische Einleitung
├── additional/                         # Kapitel die NUR dieses Projekt hat
│   ├── sonderausfuehrung_xyz.de.rst
│   └── sonderausfuehrung_xyz.en.rst
└── transport-docs-base/  ──────────── # Symlink/Mount zum Base-Repo (Share)

Details zur Konfiguration und Aufbau einer Doku siehe Kernkonzepte.

Kapitelstruktur

Kapitel	Inhalt
`00_inhaltsverzeichnis`	Wird generiert
`01_zertifikate`	CE/UKCA-Konformität, Konfigurationsbeschreibung
`02_sicherheit`	Sicherheitshinweise, Normen, Risikobewertung
`03_anlagenbeschreibung`	Module (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
`09_technische_unterlagen`	Layouts, Schaltpläne, Notstopp
`10_anhang`	Prüfberichte, Abnahmeprotokolle

Umgebungsvariablen

Variable	Beschreibung
`PROJECT`	Wurzelverzeichnis
`PV_BIN`	Skriptverzeichnis
`PV_LIB`	Python-Quellcode
`PV_CFG`	Konfigurationsdateien
`PV_DATA`	Eingabedaten
`PV_LOG`	Log-Dateien
`PV_RESULTS`	Ergebnisse
`PV_EXAMPLES`	Beispieldateien
`PYTHONPATH`	Erweitert um `PV_LIB`

Installation

Voraussetzungen

Python 3.10 oder hoeher

Setup (Windows)

bin\install_py.bat

Setup (Linux / macOS)

bash bin/install_py.sh

Nutzung

Umgebung aktivieren

bin\activate_venv.bat       # Windows

source bin/activate_venv.sh # Linux / macOS

Shell mit gesetzten Variablen oeffnen

bin\get_cmd.bat             # Windows

source bin/get_cmd.sh       # Linux / macOS

Produkt-PDFs extrahieren

Extrahiert Bilder und Text (als rST) aus den PDFs in data/Produktprogramm/:

bin\extract_products.bat    # Windows

Lizenz

MIT License -- siehe LICENSE

Autor

Michael Stangl (GitHub: mistamichael)