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
Sphinx + reStructuredText + Jinja2-Templating → LaTeX → PDF. Konfiguration via JSON (ERP-Export) + YAML (Modul-Metadaten). Bildkonvertierung: ezdxf → SVG, Pillow.
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)
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)