doc_build/README.md

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

```text
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

```text
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](doc/Kernkonzepte.md).

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

```bat
bin\install_py.bat
```

### Setup (Linux / macOS)

```bash
bash bin/install_py.sh
```

## Nutzung

### Umgebung aktivieren

```bat
bin\activate_venv.bat       # Windows
```

```bash
source bin/activate_venv.sh # Linux / macOS
```

### Shell mit gesetzten Variablen oeffnen

```bat
bin\get_cmd.bat             # Windows
```

```bash
source bin/get_cmd.sh       # Linux / macOS
```

### Produkt-PDFs extrahieren

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

```bat
bin\extract_products.bat    # Windows
```

## Lizenz

MIT License -- siehe [LICENSE](LICENSE)

## Autor

Michael Stangl (GitHub: mistamichael)