docu_build

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

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, Einbauerklärungen, Komponenten-DoCs
02_sicherheit	Sicherheitshinweise, Normen (inkl. gemeinsame/sonstige Spezifikationen), Risikobewertung (inkl. Restrisiken)
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

Details und Begründung der Unterkapitel siehe Kapitelstruktur.

Dateiformat der Textbausteine: rST und Markdown gleichwertig

Sphinx liest über die Extension MyST-Parser sowohl .rst- als auch .md-Dateien gleichwertig ein. Beide Formate können projektweit gemischt werden: ein Modul kann beschreibung.de.rst verwenden, ein anderes beschreibung.de.md – der Build behandelt beide identisch (toctree-Einbindung, Direktiven, Sprachsuffix-Konvention {name}.{lang}.{rst|md}). Empfehlung: pro Modul/Kapitel ein einheitliches Format wählen, um Lesbarkeit im Repo zu erhalten; eine Mischung ist aber technisch unproblematisch.

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)